Request & Response

Request

from veltix import Request

# Raw bytes
request = Request(MY_TYPE, b"hello")

# Text payload (UTF-8 encoded automatically)
request = Request(MY_TYPE, text="hello")

# JSON payload (serialized automatically)
request = Request(MY_TYPE, json={"key": "value"})

# With explicit request_id (uint16, 0–65535)
request = Request(MY_TYPE, b"hello", request_id=42)

Exactly one payload argument (content, text, or json) is required.

Responding to a request

Use Request.respond() to copy the request_id from a received response for correlation:

@server.route(ECHO)
def on_echo(client, response):
    reply = Request(ECHO, response.text)
    reply.respond(response)  # copies request_id
    server.send(reply, client)

veltix.network.request.Request

Represents a message request to be sent over the network.

A request contains a message type, payload content, optional request ID, and protocol flags used during serialization.

__init__

__init__(
    _type: MessageType,
    content: Any = _UNSET,
    *,
    text: Any = _UNSET,
    json: Any = _UNSET,
    request_id: Optional[int] = None,
) -> None

Initialize a new request.

Parameters:

Name	Type	Description	Default
_type	MessageType	Message type associated with this request.	required
content	Any	Raw payload bytes.	_UNSET
text	Any	UTF-8 text to encode as the payload.	_UNSET
json	Any	Python object to serialize as JSON.	_UNSET
request_id	Optional[int]	Optional identifier used to correlate the request with a response.	None

Raises:

Type	Description
RequestError	If no payload, multiple payloads, or an invalid payload type is provided.

respond

respond(response: Response) -> None

Associate this request with a received response.

Updates the request ID using the ID from the provided response, allowing request/response correlation.

Parameters:

Name	Type	Description	Default
response	Response	Response object associated with this request.	required

compile

compile() -> bytes

Serialize the request into the Veltix wire format.

Builds the protocol header, calculates the content integrity hash, and appends the raw payload.

Raises:

Type	Description
RequestError	If the payload exceeds the maximum supported size.

Returns:

Type	Description
bytes	The serialized request as bytes.

__repr__

__repr__() -> str

Return a debug representation of the request.

---

Response

def on_message(client, response):
    print(response.type.name)       # message type name
    print(response.content)         # raw bytes payload
    print(response.request_id)     # int (0–65535)

Content decoding

response.text     # str — UTF-8 decoded, cached (raises InvalidContentError)
response.json     # Any — parsed JSON, cached (raises InvalidContentError)
response.is_json  # bool — safe check, no exception
response.is_text  # bool — safe check, no exception

veltix.network.response.Response dataclass

Represents a response received through the Veltix protocol.

A response contains the message type, raw content bytes, integrity hash, and request ID used to correlate it with the original request.

Content decoding is performed lazily and cached after the first access through the :attr:text and :attr:json properties.

request_id property

request_id: int

Return the request ID associated with this response.

The request ID is used to match a response with the request that generated it.

Returns:

Type	Description
int	The request ID as an unsigned 16-bit integer.

json property

json: Any

Return the response content decoded as JSON.

The decoded value is cached after the first successful decoding.

Raises:

Type	Description
InvalidContentError	If the response content is not valid JSON.

Returns:

Type	Description
Any	The decoded JSON value.

is_json property

is_json: bool

Check whether the response content is valid JSON.

This method attempts to decode the content if it has not already been decoded. The result is cached for future accesses.

Returns:

Type	Description
bool	True if the content contains valid JSON, otherwise False.

text property

text: str

Return the response content decoded as UTF-8 text.

The decoded string is cached after the first successful decoding.

Raises:

Type	Description
InvalidContentError	If the response content is not valid UTF-8.

Returns:

Type	Description
str	The decoded text content.

is_text property

is_text: bool

Check whether the response content is valid UTF-8 text.

This method attempts to decode the content if it has not already been decoded. The result is cached for future accesses.

Returns:

Type	Description
bool	True if the content can be decoded as UTF-8 text, otherwise False.

__init__

__init__(
    _type: MessageType,
    content: bytes,
    _hash: bytes = b"",
    _request_id: int = 0,
    request_id: Optional[int] = None,
) -> None

Initialize a response object.

Parameters:

Name	Type	Description	Default
_type	MessageType	Message type associated with this response.	required
content	bytes	Raw response payload as bytes.	required
_hash	bytes	Integrity hash generated from the payload.	b''
_request_id	int	Internal request identifier used for correlation.	0
request_id	Optional[int]	Optional public request ID override.	None