Request-Response Messaging¶
This package provides a client session with request-response messaging capabilities that can be used to implement application services.
Request-response messaging allows a session to send requests to other sessions. Each receiving session provides a corresponding response, which is returned to the sending session. Each request and response carries an application provided value.
Types of Messages¶
There are three mechanisms to specify the recipient(s) of a message:
-
Send to path: The messages of this type are sent without specifying the receiving session. The server will forward an unaddressed message to any session which was registered as a handler for the path indicated in the message.
-
Send to session: Messages can be sent to a specific session by specifying its ID. To be able to respond to messages addressed to itself, a session still needs to have an internal handler.
-
Send to filter: Messages can also be addressed using a session filter. When receiving such a message, the server will locate all the currently active sessions which match the filter's conditions, and respond to the sender with the number of located sessions; the sender can expect up to that many responses, so it needs to have a handler ready to handle those responses.
diffusion.messaging.Messaging
¶
Bases: Component
Messaging component.
It is not supposed to be instantiated independently; an instance is available
on each Session
instance as session.messaging
.
RequestHandler
¶
add_stream_handler(path: str, handler: RequestHandler, addressed: bool = False) -> None
¶
Registers a request stream handler.
The handler is invoked when the session receives a request sent to the given path or session filter.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
path |
str
|
The handler will respond to the requests to this path. |
required |
handler |
RequestHandler
|
A Handler instance to handle the request. |
required |
addressed |
bool
|
|
False
|
add_filter_response_handler(session_filter: str, handler: Handler) -> None
¶
Registers a session filter response handler.
The handler is invoked when the session receives a response to a request sent to the session filter.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
session_filter |
str
|
A session filtering query. |
required |
handler |
Handler
|
A Handler instance to handle the request. |
required |
_send_request(path: str, request: dt.DataType, response_type: Optional[dt.DataTypeArgument] = None, session_id: Optional[SessionId] = None) -> Optional[dt.DataType]
async
¶
Common functionality to send a request to one or more sessions.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
path |
str
|
The path to send a request to. |
required |
request |
dt.DataType
|
The request to be sent, wrapped into the required |
required |
response_type |
Optional[dt.DataTypeArgument]
|
The type to convert the response to. If omitted, it will be
the same as the |
None
|
session_id |
Optional[SessionId]
|
If specified, the request will only be sent to the session with
that ID. If omitted, the server will forward the request to one
of the sessions registered as handlers for the given |
None
|
Returns:
Type | Description |
---|---|
Optional[dt.DataType]
|
The response value of the provided |
send_request_to_path(path: str, request: dt.DataType, response_type: Optional[dt.DataTypeArgument] = None) -> Optional[dt.DataType]
async
¶
Send a request to sessions based on a path.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
path |
str
|
The path to send a request to. |
required |
request |
dt.DataType
|
The request to be sent, wrapped into the required |
required |
response_type |
Optional[dt.DataTypeArgument]
|
The type to convert the response to. If omitted, it will be
the same as the |
None
|
Returns:
Type | Description |
---|---|
Optional[dt.DataType]
|
The response value of the provided |
add_request_handler(path: str, handler: RequestHandler, session_properties: Collection[str] = ()) -> None
async
¶
Register the session as the handler for requests to a given path.
This method is used to inform the server that any unaddressed requests to the
given path should be forwarded to the active session. The handler to
these requests is added at the same time, using add_stream_handler
internally.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
path |
str
|
The handler will respond to the requests to this path. |
required |
handler |
RequestHandler
|
A callable to handle the request. |
required |
session_properties |
Collection[str]
|
A list of keys of session properties that should be
supplied with each request. To request all fixed
properties include |
()
|
send_request_to_filter(session_filter: str, path: str, request: dt.DataType) -> int
async
¶
Send a request to other sessions, specified by the filter.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
session_filter |
str
|
A session filtering query. |
required |
path |
str
|
The path to send a request to. |
required |
request |
dt.DataType
|
The request to be sent, wrapped into the required |
required |
Returns:
Type | Description |
---|---|
int
|
The number of sessions that correspond to the filter, which is the number of |
int
|
responses that can be expected. When each of the responses is received, the |
int
|
handler registered for the filter will be executed. |
send_request_to_session(path: str, session_id: SessionId, request: dt.DataType, response_type: Optional[dt.DataTypeArgument] = None) -> Optional[dt.DataType]
async
¶
Send a request to a single session.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
path |
str
|
The path to send a request to. |
required |
session_id |
SessionId
|
The ID of the session to send the request to. |
required |
request |
dt.DataType
|
The request to be sent, wrapped into the required |
required |
response_type |
Optional[dt.DataTypeArgument]
|
The type to convert the response to. If omitted, it will be
the same as the |
None
|
Returns:
Type | Description |
---|---|
Optional[dt.DataType]
|
The response value of the provided |