Transport

REST transport layer — HTTP abstraction over requests.

All REST calls go through RestTransport. This is the single point of change when migrating the way we do the REST communication.

Classes:: ServerInfo: Parsed capabilities from GET /api/v1/info. FileAccessConfig: Parsed response from GET /api/v1/config/file-access. RestTransport: Thin HTTP client with auth, timeout, and transfer mode support. RestResponse: Lightweight response wrapper (not leaked to users).

exception mitk_workbench_remote.transport.InsecureTransportWarning

Bases: UserWarning

An API token is being sent over an unencrypted connection.

Emitted when a token is configured for a plain http:// URL whose host is not loopback: the Authorization: Bearer header then travels in cleartext and can be intercepted in transit. Prefer https for remote hosts. Silence with warnings.filterwarnings("ignore", category=InsecureTransportWarning) when the connection runs over a trusted network.

class mitk_workbench_remote.transport.TransferMode(*values)

Bases: str, Enum

Transfer modes supported by the MITK REST server.

DIRECT = 'direct'

FILE_REFERENCE = 'file-reference'

class mitk_workbench_remote.transport.FileAccessMode(*values)

Bases: str, Enum

File-access restriction modes reported by GET /api/v1/config/file-access.

UNRESTRICTED = 'unrestricted'

ALLOWED_DIRECTORIES = 'allowed-directories'

class mitk_workbench_remote.transport.ServerInfo(name, api_version, mitk_version, transfer_modes=<factory>)

Bases: object

Parsed response from GET /api/v1/info.

Parameters:

name (str) – Human-readable server name.
api_version (str) – API version string (e.g. "v1").
mitk_version (str) – Underlying MITK version string.
transfer_modes (tuple[str, ...] (default: <factory>)) – Transfer modes advertised by the server. Kept as plain strings (not TransferMode enum) so that unknown modes from future server versions are preserved rather than causing a ValueError at parse time.

name: str

api_version: str

mitk_version: str

transfer_modes: tuple[str, ...]

class mitk_workbench_remote.transport.FileAccessConfig(mode, restrictions_active, max_active_temp_dirs_per_ip, allowed_paths=<factory>)

Bases: object

Parsed response from GET /api/v1/config/file-access.

Parameters:

mode (FileAccessMode) – Access mode — FileAccessMode.UNRESTRICTED or FileAccessMode.ALLOWED_DIRECTORIES.
restrictions_active (bool) – Whether path restrictions are enforced.
max_active_temp_dirs_per_ip (int) – Server-side limit on concurrent temp directories per client IP. Used by file-reference transfer logic to avoid unexpected server-side eviction.
allowed_paths (tuple[str, ...] (default: <factory>)) – Allowed base paths when restrictions_active is True.

mode: FileAccessMode

restrictions_active: bool

max_active_temp_dirs_per_ip: int

allowed_paths: tuple[str, ...]

class mitk_workbench_remote.transport.RestResponse(response)

Bases: object

Thin wrapper around requests.Response. Never returned to users directly.

Parameters:: response (Response) – The underlying requests Response object.

property status_code: int: HTTP status code.

property ok: bool: True for 2xx responses.

property content: bytes: Raw response body as bytes.

property text: str

Raw response body as text.

Encoding is determined by requests from the Content-Type header or charset auto-detection. Use .content for endpoints that return binary data.

property headers: dict[str, str]: Response headers as a plain dict.

json()

Parse and return the JSON response body.

Return type:: Any

class mitk_workbench_remote.transport.RestTransport(base_url, *, token=None, timeout=30.0, transfer_mode=None, trust_env=None)

Bases: object

HTTP client with auth, timeout, and transfer-mode support.

All REST calls made by the library go through this class. Nothing outside this module imports the underlying used dependency directly.

Parameters:

base_url (str) – Base URL of the MITK Workbench REST server (e.g. "http://localhost:8080"). Trailing slash is stripped.
token (str | None (default: None)) – Optional API token sent as the Authorization: Bearer <token> header. Sending a token to a non-local http:// host emits an InsecureTransportWarning, since the header travels in cleartext.
timeout (float (default: 30.0)) – Request timeout in seconds. Defaults to 30.
transfer_mode (TransferMode | str | None (default: None)) – Override transfer mode (TransferMode.DIRECT or TransferMode.FILE_REFERENCE). When None (default) the mode is auto-detected on first access via server capabilities. A plain string is accepted for convenience; an unrecognised value raises ValueError immediately.
trust_env (bool | None (default: None)) – Whether to honor environment proxy settings (HTTP_PROXY / HTTPS_PROXY / NO_PROXY), the env CA bundle, and .netrc. When None (default) this is decided automatically: False for loopback targets (a forward/corporate proxy cannot route to the caller’s own machine, so honoring it would send the request to the proxy, which typically rejects it with a 403), True for remote hosts. Pass True to always honor env proxies or False to never.

property base_url: str: Base URL (without trailing slash).

property server_info: ServerInfo: Server capabilities, fetched once from GET /api/v1/info and cached.

property file_access_config: FileAccessConfig: File-reference configuration, fetched once from GET /config/file-access and cached.

property transfer_mode: TransferMode

Preferred transfer mode for data requests.

Resolution order:

Explicit value set in the constructor.
TransferMode.FILE_REFERENCE if the server advertises it in GET /api/v1/info capabilities AND the server is on localhost (filesystem access required).
TransferMode.DIRECT otherwise.

Cached after first resolution.

get(path, **kwargs)

Send a GET request.