Messages¶

MessageType¶

Every message in Veltix has a type. Types are identified by a unique integer code and a name.

Explicit code¶

from veltix import MessageType

CHAT = MessageType(code=200, name="chat", description="Chat message")
FILE = MessageType(code=201, name="file", description="File transfer")

Auto-allocated code¶

Omit the code (or pass a name string as the first argument) and Veltix will automatically assign the next available code in the 200-9999 range:

from veltix import MessageType

CHAT = MessageType("chat")                    # auto-allocates code 200
FILE = MessageType("file", description="...")  # auto-allocates code 201
STATUS = MessageType(name="status")            # keyword style, same result

Tip

Auto-allocation is ideal for quick prototyping. Use explicit codes when you need stable, predictable wire values across multiple services.

Code ranges¶

Range	Usage
0-199	System (reserved)
200-9999	User application
10000-65535	Plugins

Warning

Codes 0-199 are reserved by Veltix. Use 200+ for your own message types. The protocol supports codes up to 65535 (uint16).

Request¶

Raw bytes¶

from veltix import Request

request = Request(CHAT, b"Hello!")

Text payload¶

request = Request(CHAT, text="Hello!")  # UTF-8 encoded automatically

JSON payload¶

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

With custom request_id¶

request = Request(CHAT, b"Hello!", request_id=42)  # uint16, 0-65535

Exactly one payload argument (content, text, or json) is required. Passing zero or more than one raises RequestError.

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 from response
    server.send(reply, client)

Response¶

Responses are received in callbacks. They have the following fields and properties:

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 provides lazy, cached decoding helpers:

def on_message(client, response):
    text = response.text          # str - UTF-8 decoded, cached
    data = response.json          # Any - parsed JSON, cached
    is_json = response.is_json    # bool - safe check, no exception
    is_text = response.is_text    # bool - safe check, no exception

response.text and response.json raise InvalidContentError if the content cannot be decoded. Use response.is_text and response.is_json for safe checks without exceptions.