Whitebox

API

Standarized API of whitebox for plugins to interact with the core system.

Attributes:

Name	Type	Description
location		LocationService instance for interacting with the location service
traffic		TrafficService instance for interacting with the traffic service
status		StatusService instance for interacting with the status service
host_manager		HostManagerService instance for Host Manager access

EventEmitter

emit_sync(event_type, data)

Synchronous version of emit that properly awaits all callbacks. This is necessary because callbacks are fire-and-forget in async contexts, but in sync contexts wrapped with async_to_sync, the event loop may close before the tasks complete.

Event

add_callback(callback)

Add a callback to be executed after the event handler.

remove_callback(callback)

Remove a callback from the event.

EventRegistry

Bases: RegistryBase

Registry for managing events and their handlers. Allows registering event handlers and callbacks.

register_callback(event_type, callback)

Register a callback for an existing event.

register_event(event_type, handler, callbacks=None)

Register an event with its handler and optional callbacks.

unregister_callback(event_type, callback)

Unregister a callback for an existing event.

unregister_event(event_type)

Unregister an event by its type.

BackfillTooLarge

Bases: Exception

Raised by _run_backfill when the unfiltered count of OBSERVATION EventLog rows newer than the cursor exceeds settings.BACKFILL_LIMIT_BEFORE_RELOAD.

Callers should emit a command.session.reload frame to the client and skip the replay entirely. The reload signal IS the response on that connection — no on_connect frame follows.

BaseWebsocketConsumer

Bases: AsyncWebsocketConsumer

This consumer handles WebSocket connections for whitebox.

connect() async

Called when client connects to the WebSocket.

disconnect(close_code) async

Called when client disconnects from the WebSocket.

on_connect() async

Called when the WebSocket connection is established. This method can be overridden to handle additional logic on connect.

BaseWebsocketEventConsumer

Bases: BaseWebsocketConsumer

receive(text_data) async

Called when client sends a message to the WebSocket.

Parameters:

Name	Type	Description	Default
text_data	str	The message sent by the client.	required

MessageThrottleMixin

SquawkConsumer

Bases: MessageThrottleMixin, BaseWebsocketEventConsumer

Universal WebSocket consumer.

This consumer has no fixed consumer_group_name. Clients connect, optionally with ?all=1 to subscribe to every currently registered event type, and then send command.session.event.subscribe / command.session.event.unsubscribe frames to add or remove per-event subscriptions dynamically. Each subscription is reached by any broadcast_event(event_type, ...) and the payload is forwarded to the client verbatim.

Inbound messages that are not subscribe / unsubscribe frames fall through to BaseWebsocketEventConsumer.receive and are emitted through the regular event system.

Group-name convention: the Channels group for event_type is the string event_type itself (e.g. group "observation.status.update" for event "observation.status.update"). This must satisfy channels-redis's group_name_regex = ^[a-zA-Z\d\-_.]+$. See broadcast_group_name for the canonical accessor; do not open-code f"squawk:{event_type}" or similar in callers or tests.

broadcast_group_name(event_type) classmethod

Channels group name used to broadcast event_type.

In this codebase the group name is identical to the event name (no string prefix). squawk is a project codename, not a prefix — the convention is enforced by callers (_subscribe, _unsubscribe, events.broadcast_event) all routing through this classmethod rather than open-coding f"squawk:{event_type}" or similar.

on_connect() async

Install the per-connection replay buffer hook.

Replaces the class-level default_dispatch_message with the instance-level _buffered_dispatch for the lifetime of this connection. The hook buffers live broadcast_event deliveries that arrive during the subscribe + replay window, so the drain (_drain_replay_buffer) can dedupe them against the replay result by eid before the client sees anything.

The hook is installed BEFORE super().on_connect() runs so the bulk-throttle background tasks started by MessageThrottleMixin.on_connect already see the buffered dispatch path when they fire.

receive(text_data) async

Handle subscribe / unsubscribe frames, or fall through to emit.