delivery.account.send

Direction: modules → server. Exact event pattern: delivery.account.send.

Listener and purpose

Registered by event_handlers::EventsHandlerList::Create(Core*) in handlers/EventsHandler.hpp, independently of action handlers. The listener uses EventHandlerRecord, execution EventExecution::Inline, max_payload_size = 262144 bytes (256 KiB).

The module publishes this event when it wants to send a transient application message to active sessions identified by account login. No persisted notification is created. The current route is Core::OnSendWs(target.id, formatted_message). Delivery currently uses account WebSocket sessions. Multiple matching active sessions can receive the message.

Expected JSON structure

Input is const rapidjson::Value&, not a separately declared C++ domain record. ParseDeliveryEnvelope validates and formats it.

{
  "event_id": "run-event-123",
  "schema_version": 1,
  "created_at": 1789080000,
  "target": {
    "id": 10001
  },
  "message": {
    "type": "ai.run.delta",
    "payload": {
      "run_id": "run-123",
      "delta": "Generated text"
    }
  }
}

Parameter	Required type and constraint
event_id	Non-empty string, at most 128 bytes
schema_version	Integer, exactly 1
created_at	Positive signed 64-bit Unix timestamp
target	Object
target.id	Positive signed 32-bit integer: account login
message	Object
message.type	Non-empty string, at most 128 bytes
message.payload	JSON object; application-specific fields
Complete event payload	At most 256 KiB

Do not send a pre-serialised client frame. The Moleculer transporter supplies its own protocol envelope; the object above is the application event data. message.type is an application message category, not a separate platform listener.

Formatted client message

{
  "event": "module:event",
  "type": "ai.run.delta",
  "event_id": "run-event-123",
  "schema_version": 1,
  "created_at": 1789080000,
  "data": {
    "run_id": "run-123",
    "delta": "Generated text"
  }
}

The platform owns this transport format. The module cannot select another transport by adding a field to the request.

Errors and delivery

Internal handler results: 400 on invalid envelope; 503 if Core is unavailable; 200 after validation and invocation of the send method. These results are not returned to the publisher. Router logs payload-limit, validation and handler failures internally.

There is no delivery ACK, persistence, offline queue, receipt or exactly-once guarantee. event_id is forwarded; the handler does not implement deduplication or timestamp expiry. A successful hand-off does not prove that a matching session exists or received the data. Missing-target/transport-overflow outcomes are not returned by the current send boundary. Use an action for operations requiring confirmation or durable notifications.

See shared inbound rules and the inbound catalogue.