TuoniWebSocket¶
Connections renew before token expiry, using the client’s serialized token
refresh. Transient disconnects retry with delays of 1 to 30 seconds and restore
subscriptions. disconnect() stops recovery; connect() can restart it.
The server does not replay events missed while disconnected.
Self-signed certificates are accepted by default, matching TuoniC2(). Set
verify=True or a CA bundle path on the client to enable verification for both
REST and WebSockets. Handshake redirects follow websocket-client’s standard
handling and limit; an exhausted redirect limit is reported as a connection
failure.
Authorization, TLS and STOMP failures stop recovery. User-event subscriptions
require MANAGE_USERS; other event subscriptions require VIEW_RESOURCES.
After correcting access, refresh or log in and reconnect explicitly.
Use on_error(callback) or TuoniC2.connect_websocket(on_error=callback) for
failure notifications. Callbacks receive an exception in a daemon thread.
last_error retains the latest failure, and errors without a callback are
logged. A custom CA bundle configured on TuoniC2 also applies here.
Application events¶
The library covers all 51 server application event types and their 13 resource
topics. The server groups these topics by resource: for example,
/topic/events/by-type/NOTE carries CREATE_NOTE, UPDATE_NOTE, and
ARCHIVE_NOTE. The individual type is the event dictionary’s eventType
field.
Subscribe to a specific type with its convenience method or an EVENT_*
constant and on_event_type():
from tuoni import TuoniWebSocket
ws = client.connect_websocket()
ws.on_event_create_note(lambda event: print("Created note:", event))
ws.on_event_type(
TuoniWebSocket.EVENT_ARCHIVE_NOTE,
lambda event: print("Archived note:", event),
)
Both forms select the resource topic and filter incoming messages by
eventType. Every type has a convenience method named on_event_ followed
by its lowercase name. on_event_type() rejects unsupported types with
ValueError; noncallable callbacks raise TypeError.
To receive every event for a resource, use its on_events_* helper or
on_event(topic, callback) with a TOPIC_EVENTS_* constant:
ws.on_events_note(lambda event: print(event["eventType"]))
ws.on_event(
TuoniWebSocket.TOPIC_EVENTS_COMMAND,
lambda event: print(event["eventType"]),
)
Callbacks receive the complete, unchanged JSON event dictionary in a daemon
thread. References and their data depend on the event; CHANGE_SETTINGS
has an empty references list. Events do not refresh existing library objects.
Callbacks for the same resource share a STOMP subscription, and all registered
callbacks survive reconnection. Registering both a resource callback and a
matching type callback invokes both.
on_note(callback) remains a shorthand for on_events_note(callback);
TOPIC_NOTE and TOPIC_EVENTS_NOTE are the same destination. Note events
include their current note data in references[].data.
Resource topics¶
Every resource topic is /topic/events/by-type/ followed by the resource name
below. The USER topic requires MANAGE_USERS; the other topics require
VIEW_RESOURCES.
Resource |
Topic constant |
Callback helper |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Event types¶
Each EVENT_* constant’s string value is its name without the EVENT_
prefix. For example, EVENT_CREATE_NOTE == "CREATE_NOTE".
Event constant |
Callback helper |
Resource |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Legacy notifications¶
The original notification topics and their callback payloads remain supported.
Their payloads are specific to each topic, while application events above use
event dictionaries. In particular, on_agent_heartbeat() receives the legacy
heartbeat payload; on_event_agent_heartbeat() receives the
AGENT_HEARTBEAT event dictionary. Command-template notifications are available
through their legacy topics.
Topic constant |
Destination |
Callback helper |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
API reference¶
- class tuoni.TuoniWebSocket(c2)[source]¶
Real-time WebSocket client for the Tuoni server using SockJS/STOMP.
Subscribes to server-pushed events (agent checkins, command results, listener changes, etc.) without polling. Requires the
websocket-clientpackage.Expiring tokens and transient disconnects trigger reconnection with restored subscriptions. Permission denials and invalid authentication stop recovery. Events sent during a disconnect are not replayed by the server.
Application events use
TOPIC_EVENTS_*resource topics andEVENT_*event-type constants. Useon_events_*for a whole resource category, oron_event_*for one event type. Both receive raw event dictionaries. Existing topic callbacks retain their original payload formats.- TOPIC_AGENT¶
New agent registered.
- Type:
str
- TOPIC_AGENT_HEARTBEAT¶
Agent heartbeat/checkin.
- Type:
str
- TOPIC_AGENT_ACTIVE¶
Agent active-status change.
- Type:
str
- TOPIC_AGENT_METADATA¶
Agent metadata changed.
- Type:
str
- TOPIC_COMMAND_SENT¶
Command dispatched to agent.
- Type:
str
- TOPIC_COMMAND_RESULT¶
Command result received.
- Type:
str
- TOPIC_COMMAND_TEMPLATE_NEW¶
New command template available.
- Type:
str
- TOPIC_COMMAND_TEMPLATE_REMOVED¶
Command template removed.
- Type:
str
- TOPIC_COMMAND_ALIAS_NEW¶
New command alias available.
- Type:
str
- TOPIC_COMMAND_ALIAS_REMOVED¶
Command alias removed.
- Type:
str
- TOPIC_LISTENER_NEW¶
New listener created.
- Type:
str
- TOPIC_LISTENER_REMOVED¶
Listener deleted.
- Type:
str
- TOPIC_LISTENER_MODIFIED¶
Listener configuration changed.
- Type:
str
- TOPIC_PAYLOAD_NEW¶
New payload created.
- Type:
str
- TOPIC_PAYLOAD_ARCHIVED¶
Payload archived.
- Type:
str
- TOPIC_USER_NEW¶
New user created.
- Type:
str
- TOPIC_USER_MODIFIED¶
User modified.
- Type:
str
- TOPIC_NOTE¶
Command note created, updated or archived.
- Type:
str
Examples
>>> ws = tuoni_server.connect_websocket() >>> results = [] >>> ws.on_command_result(lambda data: results.append(data)) >>> agent.send_command(TuoniCommandLs(".", 1)) >>> # callback fires when agent returns the result
- EVENT_AGENT_HEARTBEAT = 'AGENT_HEARTBEAT'¶
- EVENT_ARCHIVE_COMMAND_ALIAS = 'ARCHIVE_COMMAND_ALIAS'¶
- EVENT_ARCHIVE_DISCOVERED_CREDENTIAL = 'ARCHIVE_DISCOVERED_CREDENTIAL'¶
- EVENT_ARCHIVE_DISCOVERED_HOST = 'ARCHIVE_DISCOVERED_HOST'¶
- EVENT_ARCHIVE_DISCOVERED_SERVICE = 'ARCHIVE_DISCOVERED_SERVICE'¶
- EVENT_ARCHIVE_NOTE = 'ARCHIVE_NOTE'¶
- EVENT_ARCHIVE_PAYLOAD = 'ARCHIVE_PAYLOAD'¶
- EVENT_BLOCK_AGENT = 'BLOCK_AGENT'¶
- EVENT_CANCEL_COMMAND = 'CANCEL_COMMAND'¶
- EVENT_CHANGE_SETTINGS = 'CHANGE_SETTINGS'¶
- EVENT_CREATE_COMMAND = 'CREATE_COMMAND'¶
- EVENT_CREATE_COMMAND_ALIAS = 'CREATE_COMMAND_ALIAS'¶
- EVENT_CREATE_COMMAND_UPDATE = 'CREATE_COMMAND_UPDATE'¶
- EVENT_CREATE_DISCOVERED_CREDENTIAL = 'CREATE_DISCOVERED_CREDENTIAL'¶
- EVENT_CREATE_DISCOVERED_HOST = 'CREATE_DISCOVERED_HOST'¶
- EVENT_CREATE_DISCOVERED_SERVICE = 'CREATE_DISCOVERED_SERVICE'¶
- EVENT_CREATE_FILE = 'CREATE_FILE'¶
- EVENT_CREATE_JOB = 'CREATE_JOB'¶
- EVENT_CREATE_LISTENER = 'CREATE_LISTENER'¶
- EVENT_CREATE_NOTE = 'CREATE_NOTE'¶
- EVENT_CREATE_PAYLOAD = 'CREATE_PAYLOAD'¶
- EVENT_CREATE_USER = 'CREATE_USER'¶
- EVENT_DEACTIVATE_AGENT = 'DEACTIVATE_AGENT'¶
- EVENT_DELETE_FILE = 'DELETE_FILE'¶
- EVENT_DELETE_LISTENER = 'DELETE_LISTENER'¶
- EVENT_EDIT_DISCOVERED_CREDENTIAL = 'EDIT_DISCOVERED_CREDENTIAL'¶
- EVENT_EDIT_DISCOVERED_HOST = 'EDIT_DISCOVERED_HOST'¶
- EVENT_EDIT_DISCOVERED_SERVICE = 'EDIT_DISCOVERED_SERVICE'¶
- EVENT_LOGIN_USER = 'LOGIN_USER'¶
- EVENT_MODIFY_AGENT_METADATA = 'MODIFY_AGENT_METADATA'¶
- EVENT_REACTIVATE_AGENT = 'REACTIVATE_AGENT'¶
- EVENT_RECEIVE_COMMAND_RESULT = 'RECEIVE_COMMAND_RESULT'¶
- EVENT_RECOVER_COMMAND = 'RECOVER_COMMAND'¶
- EVENT_RECOVER_LISTENER = 'RECOVER_LISTENER'¶
- EVENT_RECOVER_PAYLOAD = 'RECOVER_PAYLOAD'¶
- EVENT_REGISTER_AGENT = 'REGISTER_AGENT'¶
- EVENT_RESTORE_DISCOVERED_CREDENTIAL = 'RESTORE_DISCOVERED_CREDENTIAL'¶
- EVENT_RESTORE_DISCOVERED_HOST = 'RESTORE_DISCOVERED_HOST'¶
- EVENT_RESTORE_DISCOVERED_SERVICE = 'RESTORE_DISCOVERED_SERVICE'¶
- EVENT_SEND_COMMAND = 'SEND_COMMAND'¶
- EVENT_SEND_COMMAND_UPDATE = 'SEND_COMMAND_UPDATE'¶
- EVENT_START_LISTENER = 'START_LISTENER'¶
- EVENT_STOP_LISTENER = 'STOP_LISTENER'¶
- EVENT_UPDATE_AGENT_METADATA = 'UPDATE_AGENT_METADATA'¶
- EVENT_UPDATE_COMMAND_ALIAS = 'UPDATE_COMMAND_ALIAS'¶
- EVENT_UPDATE_FILE = 'UPDATE_FILE'¶
- EVENT_UPDATE_JOB = 'UPDATE_JOB'¶
- EVENT_UPDATE_LISTENER = 'UPDATE_LISTENER'¶
- EVENT_UPDATE_NOTE = 'UPDATE_NOTE'¶
- EVENT_UPDATE_PAYLOAD = 'UPDATE_PAYLOAD'¶
- EVENT_UPDATE_USER = 'UPDATE_USER'¶
- TOPIC_EVENTS_AGENT = '/topic/events/by-type/AGENT'¶
- TOPIC_EVENTS_COMMAND = '/topic/events/by-type/COMMAND'¶
- TOPIC_EVENTS_COMMAND_ALIAS = '/topic/events/by-type/COMMAND_ALIAS'¶
- TOPIC_EVENTS_DISCOVERED_CREDENTIAL = '/topic/events/by-type/DISCOVERED_CREDENTIAL'¶
- TOPIC_EVENTS_DISCOVERED_HOST = '/topic/events/by-type/DISCOVERED_HOST'¶
- TOPIC_EVENTS_DISCOVERED_SERVICE = '/topic/events/by-type/DISCOVERED_SERVICE'¶
- TOPIC_EVENTS_FILE = '/topic/events/by-type/FILE'¶
- TOPIC_EVENTS_JOB = '/topic/events/by-type/JOB'¶
- TOPIC_EVENTS_LISTENER = '/topic/events/by-type/LISTENER'¶
- TOPIC_EVENTS_NOTE = '/topic/events/by-type/NOTE'¶
- TOPIC_EVENTS_PAYLOAD = '/topic/events/by-type/PAYLOAD'¶
- TOPIC_EVENTS_SETTING = '/topic/events/by-type/SETTING'¶
- TOPIC_EVENTS_USER = '/topic/events/by-type/USER'¶
- connect(timeout: float = 10) bool[source]¶
Connect to the server’s WebSocket endpoint and complete the STOMP handshake.
- Parameters:
timeout (float) – Seconds to wait for the STOMP CONNECTED frame.
- Returns:
True if the STOMP session was established within
timeoutseconds.- Return type:
bool
Examples
>>> ws = TuoniWebSocket(tuoni_server) >>> if not ws.connect(): >>> print("WebSocket connection failed")
- property is_connected: bool¶
True if the STOMP session is active.
- on_error(callback)[source]¶
Register callback(exception) for connection, authorization and protocol errors.
Callbacks run in daemon threads. The most recent error is also available as
last_error. Without a callback, errors are logged as warnings.
- on_event(topic: str, callback)[source]¶
Subscribe to a STOMP topic and register a callback.
If already connected the subscription is sent immediately; otherwise it is queued and sent once the STOMP session is established.
- Parameters:
topic (str) – STOMP topic (e.g.
TuoniWebSocket.TOPIC_COMMAND_RESULT).callback (callable) – Called with the deserialized JSON payload when a message arrives. Runs in a daemon thread.
Examples
>>> ws.on_event(TuoniWebSocket.TOPIC_AGENT, lambda data: print("new agent:", data))
- on_event_agent_heartbeat(callback)[source]¶
Register a callback for
AGENT_HEARTBEATapplication events (raw JSON).
- on_event_archive_command_alias(callback)[source]¶
Register a callback for
ARCHIVE_COMMAND_ALIASapplication events (raw JSON).
- on_event_archive_discovered_credential(callback)[source]¶
Register a callback for
ARCHIVE_DISCOVERED_CREDENTIALapplication events (raw JSON).
- on_event_archive_discovered_host(callback)[source]¶
Register a callback for
ARCHIVE_DISCOVERED_HOSTapplication events (raw JSON).
- on_event_archive_discovered_service(callback)[source]¶
Register a callback for
ARCHIVE_DISCOVERED_SERVICEapplication events (raw JSON).
- on_event_archive_note(callback)[source]¶
Register a callback for
ARCHIVE_NOTEapplication events (raw JSON).
- on_event_archive_payload(callback)[source]¶
Register a callback for
ARCHIVE_PAYLOADapplication events (raw JSON).
- on_event_block_agent(callback)[source]¶
Register a callback for
BLOCK_AGENTapplication events (raw JSON).
- on_event_cancel_command(callback)[source]¶
Register a callback for
CANCEL_COMMANDapplication events (raw JSON).
- on_event_change_settings(callback)[source]¶
Register a callback for
CHANGE_SETTINGSapplication events (raw JSON).
- on_event_create_command(callback)[source]¶
Register a callback for
CREATE_COMMANDapplication events (raw JSON).
- on_event_create_command_alias(callback)[source]¶
Register a callback for
CREATE_COMMAND_ALIASapplication events (raw JSON).
- on_event_create_command_update(callback)[source]¶
Register a callback for
CREATE_COMMAND_UPDATEapplication events (raw JSON).
- on_event_create_discovered_credential(callback)[source]¶
Register a callback for
CREATE_DISCOVERED_CREDENTIALapplication events (raw JSON).
- on_event_create_discovered_host(callback)[source]¶
Register a callback for
CREATE_DISCOVERED_HOSTapplication events (raw JSON).
- on_event_create_discovered_service(callback)[source]¶
Register a callback for
CREATE_DISCOVERED_SERVICEapplication events (raw JSON).
- on_event_create_file(callback)[source]¶
Register a callback for
CREATE_FILEapplication events (raw JSON).
- on_event_create_job(callback)[source]¶
Register a callback for
CREATE_JOBapplication events (raw JSON).
- on_event_create_listener(callback)[source]¶
Register a callback for
CREATE_LISTENERapplication events (raw JSON).
- on_event_create_note(callback)[source]¶
Register a callback for
CREATE_NOTEapplication events (raw JSON).
- on_event_create_payload(callback)[source]¶
Register a callback for
CREATE_PAYLOADapplication events (raw JSON).
- on_event_create_user(callback)[source]¶
Register a callback for
CREATE_USERapplication events (raw JSON).
- on_event_deactivate_agent(callback)[source]¶
Register a callback for
DEACTIVATE_AGENTapplication events (raw JSON).
- on_event_delete_file(callback)[source]¶
Register a callback for
DELETE_FILEapplication events (raw JSON).
- on_event_delete_listener(callback)[source]¶
Register a callback for
DELETE_LISTENERapplication events (raw JSON).
- on_event_edit_discovered_credential(callback)[source]¶
Register a callback for
EDIT_DISCOVERED_CREDENTIALapplication events (raw JSON).
- on_event_edit_discovered_host(callback)[source]¶
Register a callback for
EDIT_DISCOVERED_HOSTapplication events (raw JSON).
- on_event_edit_discovered_service(callback)[source]¶
Register a callback for
EDIT_DISCOVERED_SERVICEapplication events (raw JSON).
- on_event_login_user(callback)[source]¶
Register a callback for
LOGIN_USERapplication events (raw JSON).
- on_event_modify_agent_metadata(callback)[source]¶
Register a callback for
MODIFY_AGENT_METADATAapplication events (raw JSON).
- on_event_reactivate_agent(callback)[source]¶
Register a callback for
REACTIVATE_AGENTapplication events (raw JSON).
- on_event_receive_command_result(callback)[source]¶
Register a callback for
RECEIVE_COMMAND_RESULTapplication events (raw JSON).
- on_event_recover_command(callback)[source]¶
Register a callback for
RECOVER_COMMANDapplication events (raw JSON).
- on_event_recover_listener(callback)[source]¶
Register a callback for
RECOVER_LISTENERapplication events (raw JSON).
- on_event_recover_payload(callback)[source]¶
Register a callback for
RECOVER_PAYLOADapplication events (raw JSON).
- on_event_register_agent(callback)[source]¶
Register a callback for
REGISTER_AGENTapplication events (raw JSON).
- on_event_restore_discovered_credential(callback)[source]¶
Register a callback for
RESTORE_DISCOVERED_CREDENTIALapplication events (raw JSON).
- on_event_restore_discovered_host(callback)[source]¶
Register a callback for
RESTORE_DISCOVERED_HOSTapplication events (raw JSON).
- on_event_restore_discovered_service(callback)[source]¶
Register a callback for
RESTORE_DISCOVERED_SERVICEapplication events (raw JSON).
- on_event_send_command(callback)[source]¶
Register a callback for
SEND_COMMANDapplication events (raw JSON).
- on_event_send_command_update(callback)[source]¶
Register a callback for
SEND_COMMAND_UPDATEapplication events (raw JSON).
- on_event_start_listener(callback)[source]¶
Register a callback for
START_LISTENERapplication events (raw JSON).
- on_event_stop_listener(callback)[source]¶
Register a callback for
STOP_LISTENERapplication events (raw JSON).
- on_event_type(event_type: str, callback)[source]¶
Register a callback for a single application event type.
The server groups application events by resource topic. This method subscribes to the matching topic and filters its messages by
eventType. Multiple callbacks share one STOMP subscription per topic, including after reconnection.- Parameters:
event_type (str) – A supported
EVENT_*constant, such asTuoniWebSocket.EVENT_CREATE_NOTE.callback (callable) – Receives the unchanged event dictionary, including
eventType,actor,parentEventandreferences. Runs in a daemon thread.
- Raises:
TypeError – If callback is not callable.
ValueError – If event_type is not a supported event type.
User events require
MANAGE_USERS; other application events requireVIEW_RESOURCES. Unknown future event types can still be received throughon_event(topic, callback)or the category callbacks.Examples
>>> ws.on_event_type(TuoniWebSocket.EVENT_CREATE_NOTE, print)
- on_event_update_agent_metadata(callback)[source]¶
Register a callback for
UPDATE_AGENT_METADATAapplication events (raw JSON).
- on_event_update_command_alias(callback)[source]¶
Register a callback for
UPDATE_COMMAND_ALIASapplication events (raw JSON).
- on_event_update_file(callback)[source]¶
Register a callback for
UPDATE_FILEapplication events (raw JSON).
- on_event_update_job(callback)[source]¶
Register a callback for
UPDATE_JOBapplication events (raw JSON).
- on_event_update_listener(callback)[source]¶
Register a callback for
UPDATE_LISTENERapplication events (raw JSON).
- on_event_update_note(callback)[source]¶
Register a callback for
UPDATE_NOTEapplication events (raw JSON).
- on_event_update_payload(callback)[source]¶
Register a callback for
UPDATE_PAYLOADapplication events (raw JSON).
- on_event_update_user(callback)[source]¶
Register a callback for
UPDATE_USERapplication events (raw JSON).
- on_events_command(callback)[source]¶
Register a callback for all
COMMANDapplication events (raw JSON).
- on_events_command_alias(callback)[source]¶
Register a callback for all
COMMAND_ALIASapplication events (raw JSON).
- on_events_discovered_credential(callback)[source]¶
Register a callback for all
DISCOVERED_CREDENTIALapplication events (raw JSON).
- on_events_discovered_host(callback)[source]¶
Register a callback for all
DISCOVERED_HOSTapplication events (raw JSON).
- on_events_discovered_service(callback)[source]¶
Register a callback for all
DISCOVERED_SERVICEapplication events (raw JSON).
- on_events_listener(callback)[source]¶
Register a callback for all
LISTENERapplication events (raw JSON).
- on_events_payload(callback)[source]¶
Register a callback for all
PAYLOADapplication events (raw JSON).
- on_events_setting(callback)[source]¶
Register a callback for all
SETTINGapplication events (raw JSON).
- on_note(callback)[source]¶
Register a callback for command note events.
- Parameters:
callback (callable) – Receives the raw JSON event for
CREATE_NOTE,UPDATE_NOTEorARCHIVE_NOTE. Note data is included inreferences[].data. Runs in a daemon thread.
Requires
VIEW_RESOURCES. Existing note objects are not updated automatically, and events missed during disconnection are not replayed.