Skip to content

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

Bases: Handler

Handler for messaging requests.

handle async

handle(event: str = 'request', **kwargs) -> dt.DataType

Execute the callback.

add_stream_handler

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

True to handle the requests addressed to the session's ID or using a session filter; False for unaddressed requests.

False

add_filter_response_handler

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_to_path async

send_request_to_path(path: str, request: dt.DataType, response_type: Optional[dt.DataTypeArgument] = None) -> Optional[dt.DataType]

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 DataType class.

required
response_type Optional[dt.DataTypeArgument]

The type to convert the response to. If omitted, it will be the same as the request's data type.

None

Returns:

Type Description
Optional[dt.DataType]

The response value of the provided response_type.

add_request_handler async

add_request_handler(path: str, handler: RequestHandler, session_properties: Collection[str] = ()) -> None

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 ALL_FIXED_PROPERTIES as a key; any other fixed property keys will be ignored. To request all user properties include ALL_USER_PROPERTIES as a key; any other user properties will be ignored.

()

send_request_to_filter async

send_request_to_filter(session_filter: str, path: str, request: dt.DataType) -> int

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 DataType class.

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 async

send_request_to_session(path: str, session_id: SessionId, request: dt.DataType, response_type: Optional[dt.DataTypeArgument] = None) -> Optional[dt.DataType]

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 DataType class.

required
response_type Optional[dt.DataTypeArgument]

The type to convert the response to. If omitted, it will be the same as the request's data type.

None

Returns:

Type Description
Optional[dt.DataType]

The response value of the provided response_type.