request

Send a request by protocol method name and return its decoded result.

Call a canonical Herdr socket method and return its result.

Use the convenience methods when one exists. This low-level operation is useful for canonical protocol methods that do not yet have a wrapper.

Parameters:

Name	Type	Description	Default
method	str	Canonical JSON method name, such as "pane.read".	required
params	object | None	JSON object containing method parameters, or None for an empty parameter object.	None

Returns:

Type	Description
ResponseResult	The validated result object returned by Herdr.

Raises:

Type	Description
HerdrClientError	If the method is unsupported or the socket exchange fails.
TypeError	If params is not a mapping.
HerdrApiError	If Herdr returns an error envelope.

Example

await client.request("workspace.list")
await client.request("pane.read", {"pane_id": "build"})

Source code in src/herdr_client/async_client/client.py

async def request(
    self, method: str, params: object | None = None
) -> ResponseResult:
    """Call a canonical Herdr socket method and return its result.

    Use the convenience methods when one exists. This low-level operation is
    useful for canonical protocol methods that do not yet have a wrapper.

    Args:
        method: Canonical JSON method name, such as ``"pane.read"``.
        params: JSON object containing method parameters, or ``None`` for an
            empty parameter object.

    Returns:
        The validated result object returned by Herdr.

    Raises:
        HerdrClientError: If the method is unsupported or the socket exchange
            fails.
        TypeError: If ``params`` is not a mapping.
        HerdrApiError: If Herdr returns an error envelope.

    Example:
        ```python
        await client.request("workspace.list")
        await client.request("pane.read", {"pane_id": "build"})
        ```
    """
    if method not in CANONICAL_METHODS:
        raise HerdrClientError(f"unsupported herdr socket method: {method}")

    reader, writer = await connect_socket(self.socket_path, self.timeout)
    try:
        if params is None:
            request_params: Mapping[str, JSONValue] = {}
        elif isinstance(params, Mapping):
            request_params = cast("Mapping[str, JSONValue]", params)
        else:
            raise TypeError("herdr request params must be a mapping")
        await send_envelope(
            writer,
            self.timeout,
            {
                "id": new_id(),
                "method": method,
                "params": request_params,
            },
        )
        response = await read_json_line(reader, self.timeout)
        return response_result(response)
    finally:
        await close_writer(writer)