API¶
Preconnection¶
- class
Preconnection
(local_endpoint=None, remote_endpoint=None, transport_properties=None, security_needed=False, unfulfilled_handler=None)¶A Preconnection represents a set of properties and constraints on the selection and configuration of paths and protocols to establish a Connection with a remote Endpoint.
- Parameters
local_endpoint (
Optional
[LocalEndpoint
]) – Optional local endpoint to be used with the Preconnectionremote_endpoint (
Optional
[RemoteEndpoint
]) – Optional remote endpoint to be used with the Preconnectiontransport_properties (
Optional
[TransportProperties
]) – A transport property object with desired Selection Properties.security_needed (
bool
) – Indicated whether or not a secure connection is needed.unfulfilled_handler (
Optional
[Callable
[[],None
]]) – A function handling an unfulfilled error
add_framer
(framer)¶Adds a framer to the Preconnection to run on top of transport protocols. Multiple Framers may be added. If multiple Framers are added, the last one added runs first when framing outbound messages, and last when parsing inbound data.
- Parameters
framer – The framer to be added. Must inherit from the
framer
class and implement its abstract functions.- Return type
None
initiate
(timeout=None)¶Initiate (Active open) is the Action of establishing a Connection to a Remote Endpoint presumed to be listening for incoming Connection requests. Active open is used by clients in client-server interactions. Note that start() must be called on the Preconnection.
- Parameters
timeout – The timeout parameter specifies how long to wait before aborting Active open.
- Return type
initiate_with_send
(message_data, sent_handler, message_context=None, timeout=None)¶For application-layer protocols where the Connection initiator also sends the first message, the InitiateWithSend() action combines Connection initiation with a first Message sent. Returns a Connection object in the
establishing
state.
- Parameters
message_data (
bytearray
) – The message to be sentsent_handler (
Callable
[[Connection
,SendErrorReason
],None
]) – A function / completion handler, handling both a successful completion and errors.message_context (
Optional
[MessageContext
]) – Optional, used to indicate the message is idempotent, so it possibly can be used with 0-RTT establishment, if supported by the transport stack and system.timeout (
Optional
[int
]) – The timeout parameter specifies how long to wait before aborting Active open.- Return type
listen
()¶Listen (Passive open) is the Action of waiting for Connections from remote Endpoints. Before listening the transport system will resolve transport properties for candidate protocol stacks. A local endpoint must be passed to the Preconnection prior to listen.
- Return type
Listener
- Returns
A listener object.
start
()¶Starts the transport systems. Must be called after initiate / listen.
- Return type
None
- Returns
This function does not return.
Connection¶
-
class
ConnectionState
(value)¶ An enumeration of the different states for a connection.
-
CLOSED
= 4¶
-
CLOSING
= 3¶
-
ESTABLISHED
= 2¶
-
ESTABLISHING
= 1¶
-
-
class
MessageDataObject
(data, length)¶ The messageData object provides access to the bytes that were received for a Message, along with the length of the byte array. It is passed to applications during the receive event, signaling a completion of a
receive()
call.-
data
: bytearray¶ The raw bytes of the message
-
length
: int¶ The message length
-
-
class
Connection
¶ A Connection represents a transport Protocol Stack on which data can be sent to and/or received from a remote Endpoint (i.e., depending on the kind of transport, connections can be bi-directional or unidirectional).
A Connection is created from a
preconnection
with active or passive open, or cloning, i.e it cannot be instantiated directly.-
HANDLE_STATE_CLOSED
: Callable[[Connection], None]¶ Handler for when the connection transitions to closed state
-
HANDLE_STATE_CONNECTION_ERROR
: Callable[[Connection], None]¶ Handler for when the connection gets experiences a connection error
-
HANDLE_STATE_READY
: Callable[[Connection], None]¶ Handler for when the connection transitions to ready state
-
abort
()¶ Abort terminates a Connection without delivering remaining data.
- Return type
None
-
batch
(batch_block)¶ Used to send multiple messages without the transport system dispatching messages further down the stack. Used to minimize overhead, and as a mechanism for the application to indicate that messages could be coalesced when possible.
- Parameters
batch_block (
Callable
[[],None
]) – A function / block of code which calls send multiple times- Return type
None
-
clone
(clone_error_handler)¶ Calling Clone on a Connection yields a group of two Connections: the parent Connection on which Clone was called, and the resulting cloned Connection. These connections are “entangled” with each other, and become part of a Connection Group. Calling Clone on any of these two Connections adds a third Connection to the Connection Group, and so on. Connections in a Connection Group generally share
connection_properties
. However, there are exceptions, such as the priority property, which obviously will not trigger a change for all connections in the connection group. As with all other properties, priority is copied to the new Connection when calling Clone().- Parameters
clone_error_handler (
Callable
[[Connection
],None
]) – A function to handle the event which fires when the cloning operation fails. The connection which clone was called on is sent with the handler.- Return type
None
-
close
()¶ Close terminates a Connection after satisfying all the requirements that were specified regarding the delivery of Messages that the application has already given to the transport system. For example, if reliable delivery was requested for a Message handed over before calling Close, the transport system will ensure that this Message is indeed delivered. If the Remote Endpoint still has data to send, it cannot be received after this call.
- Return type
None
-
get_properties
()¶ Returns a dictionary consisting of the connections properties, which include the following:
connection_state
- key'state'
A boolean which holds the value for whether the connection can be used for sending - key
'send'
A boolean which holds the value for whether the connection can be used for receiving - key
'receive'
- A
transport_properties
object, which will differ with the connection’s state - key'props'
A connection in an establishing phase will hold transport properties that the application specified with the
preconnection
.A connection in either an established, closing or closed state will hold the
selection_properties
andconnection_properties
of the actual protocols that were selected and instantiated.
- A
An example showing an application checking if the connection can be used for sending:
returned_props_dict = connection.get_properties() can_be_used_for_sending = returned_props_dict['send'] if can_be_used_for_sending: ...
- Return type
None
-
receive
(handler, min_incomplete_length=None, max_length=inf)¶ As with sending, data is received in terms of Messages. Receiving is an asynchronous operation, in which each call to Receive enqueues a request to receive new data from the connection. Once data has been received, or an error is encountered, an event will be delivered to complete the Receive request.
- Parameters
handler (
Callable
[[Connection
,MessageDataObject
,MessageContext
,bool
,bool
],None
]) – The function to handle the event delivered during completion, which includes both potential errors and successfully received data.min_incomplete_length (
Optional
[int
]) – The defaultNone
value indicates that only complete messages should be delivered. Setting it to anything other than this will trigger a receive event only when at least that many bytes are available.max_length (
int
) – Indicates the maximum size of a message in bytes the application is prepared to receive. Incoming messages larger than this will be delivered in received partial events. To determine whether the received event is a partial event the application is able to check whether the variableis_end_of_message
holds the boolean value False, which indicates a partial event, while a None value indicates a complete message being delivered.
- Return type
None
-
send
(message_data, sent_handler=None, message_context=None, end_of_message=True)¶ Data is sent as Messages, which allow the application to communicate the boundaries of the data being transferred. By default, Send enqueues a complete Message, and takes optional per-
message_properties
. Applications are able to handle events with the :param sent_handler. This handles completion in form of an either an error or a successfully sent message.- Parameters
message_data (
bytearray
) – The data to send.sent_handler (
Optional
[Callable
[[Connection
,SendErrorReason
],None
]]) – A function that is called after completion / error.message_context (
Optional
[MessageContext
]) – Additionalmessage_properties
can be sent by adding them to a Message Context object Optinoal.end_of_message (
bool
) – When set to false indicates a partial send. All data sent with the same MessageContext object will be treated as belonging to the same Message, and will constitute an in-order series until the endOfMessage is marked.
- Return type
None
-
set_property
(connection_property, value)¶ The application can set and query Connection Properties on a per-Connection basis. Connection Properties that are not read-only can be set during pre-establishment (see
connection_properties
) as well as on connections directly using the SetProperty action:- Parameters
connection_property (
ConnectionProperties
) – The property to assign a value.value – The value to assign the property.
- Return type
None
-
Transport Properties¶
-
class
TransportProperties
(property_profile=None)¶ Transport properties is the collection of
message_properties
,selection_properties
andconnection_properties
.- Parameters
property_profile (
Optional
[TransportPropertyProfiles
]) – Transport property profile to use
-
add
(prop, value)¶ Add a property to the transport property object.
- Parameters
prop (
Union
[SelectionProperties
,MessageProperties
,ConnectionProperties
]) – Property to addvalue – Value for given property
- Return type
None
-
avoid
(prop)¶ Set the preference level to avoid for the passed selection property.
- Parameters
prop (
SelectionProperties
) – Selection property to setavoid
as preference level for.- Return type
None
-
default
(prop)¶ Set the default preference level for the given selection property.
- Parameters
prop (
SelectionProperties
) – Selection property to reset to default preference level for.
-
ignore
(prop)¶ Set the preference level to ignore for the passed selection property.
- Parameters
prop (
SelectionProperties
) – Selection property to setignore
as preference level for.- Return type
None
-
prefer
(prop)¶ Set the preference level to prefer for the passed selection property.
- Parameters
prop (
SelectionProperties
) – Selection property to setprefer
as preference level for.- Return type
None
-
prohibit
(prop)¶ Set the preference level to prohibit for the passed selection property.
- Parameters
prop (
SelectionProperties
) – Selection property to setprohibit
as preference level for.- Return type
None
-
require
(prop)¶ Set the preference level to require for the passed selection property.
- Parameters
prop (
SelectionProperties
) – Selection property to setrequire
as preference level for.- Return type
None
-
class
TransportPropertyProfiles
(value)¶ Transport property profiles are used as a mechanism to pre-configure
transport_properties
objects, with frequently used sets of properties.-
RELIABLE_INORDER_STREAM
= 1¶ This profile provides a reliable, in-order transport service with congestion control. An example of a protocol that provides this service is TCP.
-
RELIABLE_MESSAGE
= 2¶ This profile provides message-preserving, reliable, in-order transport service with congestion control. An example of a protocol that provides this service is SCTP.
-
UNRELIABLE_DATAGRAM
= 3¶ This profile provides an unreliable datagram transport service. An example of a protocol that provides this service is UDP.
-
Selection Properties¶
-
class
PreferenceLevel
(value)¶ An enumeration. Used when specifying a preference for
selection_properties
.E.g an application specifying that a reliable transport is required would do this the following way:
transport_properties.add(SelectionProperties.RELIABILITY, PreferenceLevel.REQUIRE)
-
AVOID
= -1¶
-
IGNORE
= 0¶
-
PREFER
= 1¶
-
PROHIBIT
= -2¶
-
REQUIRE
= 2¶
-
-
class
SelectionProperties
(value)¶ An enumeration. Selection properties are used for application to specify applications requirements for transport and used for path and protocol stack selections. Selection properties are added to a
transport_properties
object.-
CONGESTION_CONTROL
= 'congestion-control'¶ Default
preference_level
.REQUIRE,
-
DIRECTION
= 'direction'¶ Default
communication_directions
-
INTERFACE
= 'interface'¶ Default
preference_level
-
LOCAL_ADDRESS_PREFERENCE
= 'local-address-preference'¶ Default
preference_level
-
MULTIPATH
= 'multipath'¶ Default
preference_level
.PREFER
-
MULTISTREAMING
= 'multistreaming'¶ Default
preference_level
.PREFER,
-
PER_MSG_CHECKSUM_LEN_RECV
= 'per-msg-checksum-len-recv'¶ Default
preference_level
.IGNORE,
-
PER_MSG_CHECKSUM_LEN_SEND
= 'per-msg-checksum-len-send'¶ Default
preference_level
.IGNORE,
-
PER_MSG_RELIABILITY
= 'per-msg-reliability'¶ Default
preference_level
.IGNORE,
-
PRESERVE_MSG_BOUNDARIES
= 'preserve-msg-boundaries'¶ Default
preference_level
.PREFER,
-
PRESERVE_ORDER
= 'preserve-order'¶ Default
preference_level
.REQUIRE,
-
PVD
= 'pvd'¶ Default
preference_level
-
RELIABILITY
= 'reliability'¶ Default
preference_level
.REQUIRE,
-
RETRANSMIT_NOTIFY
= 'retransmit-notify'¶ Default
preference_level
.IGNORE
-
SOFT_ERROR_NOTIFY
= 'soft-error-notify'¶ Default
preference_level
.IGNORE
-
ZERO_RTT_MSG
= 'zero-rtt-msg'¶ Default
preference_level
.IGNORE,
-
Connection Properties¶
-
class
CapacityProfiles
(value)¶ By specifying a Capacity Profile, an application is able to signal what kind of network treatment it desires. Under the hood the transport system will map each profile to different DSCP values for the given Connection.
-
CAPACITY_SEEKING
= 10¶ Sending and receiving at the maximum rate allowed by the Connection’s congestion controller.
-
CONSTANT_RATE_STREAMING
= 28¶ Sending and receiving at a constant rate is desired. Minimal delay is wanted.
-
DEFAULT
= 0¶ No explicit information for expected capacity profile is given.
-
LOW_LATENCY_INTERACTIVE
= 36¶ An interactive Connection. Loss is preferred over latency.
-
LOW_LATENCY_NON_INTERACTIVE
= 18¶ Loss is preferred to latency, but the Connection is non-interactive.
-
SCAVENGER
= 1¶ A non-interactive Connection. The data is sent without any urgency for either sending or receiving.
-
-
class
ConnectionProperties
(value)¶ Connection Properties represent the configuration and state of the selected Protocol Stack(s) backing a Connection. The application can set and query Connection Properties on a per-Connection basis. Connection Properties that are not read-only can be set prior to a call to either
initiate()
orlisten()
.-
BOUNDS_ON_SEND_OR_RECEIVE_RATE
= 'max-send-rate / max-recv-rate'¶ Default value is (-1, -1)
-
CAPACITY_PROFILE
= 'conn-capacity-profile'¶ Default value is
CapacityProfiles
-
CONNECTION_GROUP_TRANSMISSION_SCHEDULER
= 'conn-scheduler'¶ Default value is “Weighted fair queueing”
-
MAXIMUM_MESSAGE_SIZE_BEFORE_FRAGMENTATION_OR_SEGMENTATION
= 'singular-transmission-msg-max-len'¶ Default value is -1
-
MAXIMUM_MESSAGE_SIZE_CONCURRENT_WITH_CONNECTION_ESTABLISHMENT
= 'zero-rtt-msg-max-len'¶ Default value is -1
-
MAXIMUM_MESSAGE_SIZE_ON_RECEIVE
= 'recv-msg-max-len'¶ Default value is -1
-
MAXIMUM_MESSAGE_SIZE_ON_SEND
= 'send-msg-max-len'¶ Default value is -1
-
PRIORITY
= 'conn-prio'¶ Default value is 100
-
REQUIRED_MINIMUM_CORRUPTION_PROTECTION_COVERAGE_FOR_RECEIVING
= 'recv-checksum-len'¶ Default value is -1
-
RETRANSMISSION_THRESHOLD_BEFORE_EXCESSIVE_RETRANSMISSION_NOTIFICATION
= 'retransmit-notify-threshold'¶ Default value is -1
-
TIMEOUT_FOR_ABORTING_CONNECTION
= 'conn-timeout'¶ Default value is -1
-
USER_TIMEOUT_TCP
= 'tcp-uto'¶ An enumeration of three values, see
TCPUserTimeout
.
-
-
class
TCPUserTimeout
(value)¶ These properties specify configurations for the User Timeout Option (UTO), in case TCP becomes the chosen transport protocol.
To set a property of TCP UTO, pass a dictionary with one or more properties:
tcp_uto_dict = {TCPUserTimeout.ADVERTISED_USER_TIMEOUT: 150} transport_properties_object.add(ConnectionProperties.USER_TIMEOUT_TCP, tcp_uto_dict)
-
ADVERTISED_USER_TIMEOUT
= 'tcp.user-timeout-value'¶ This time value is advertised via the TCP User Timeout Option (UTO) - Default 300 seconds.
-
CHANGEABLE
= 'tcp.user-timeout-recv'¶ This property controls whether the Timeout for aborting Connection may be changed based on a UTO option received from the remote peer - Default True
-
USER_TIMEOUT_ENABLED
= 'tcp.user-timeout'¶ This property controls whether the UTO option is enabled for a connection - Default False`
-
Message Properties¶
- class
MessageProperties
(value)¶Message Properties are used by the application to annotate the Messages they send with extra information to control how data is scheduled and processed by the transport protocols in the
connection
. Message Properties are sent by adding them to amessage_context
, and pass said context to thesend()
call.
CORRUPTION_PROTECTION_LENGTH
= 'msg-checksum-len'¶Default value is -1
EARLY_DATA
= 'early-data'¶Read only property
ECN
= 'ecn'¶Read only property
FINAL
= 'final'¶Default value is False
IDEMPOTENT
= 'idempotent'¶Default value is False
LIFETIME
= 'msg-lifetime'¶Default value is math.inf
MESSAGE_CAPACITY_PROFILE_OVERRIDE
= 'msg-capacity-profile'¶Default value is CapacityProfiles.DEFAULT
ORDERED
= 'msg-ordered'¶Default value is True
PRIORITY
= 'msg-prio'¶Default value is 100
RECEIVING_FINAL_MESSAGE
= 'receiving-final-messages'¶Read only property
RELIABLE_DATA_TRANSFER
= 'msg-reliable'¶Default value is True
SINGULAR_TRANSMISSION
= 'singular-transmission'¶Default value is False
Endpoints¶
-
class
LocalEndpoint
¶ This class holds information about a local endpoint. It could be passed when initiating a
preconnection
. Furthermore it is required when trying to establish a connection with a remote endpoint withlisten()
.-
with_address
(address)¶ This function sets the address desired to use with the local endpoint.
- Parameters
address (
str
) – The address to set.- Return type
None
-
with_interface
(interface)¶ This function sets the interface desired to with the local endpoint.
- Parameters
interface (
str
) – The endpoint to set.- Return type
None
-
with_port
(port_number)¶ This function sets the port desired to use with the local endpoint.
- Parameters
port_number (
int
) – The port to set.- Return type
None
-
-
class
RemoteEndpoint
¶ This class holds information about a remote endpoint. It could be passed when initiating a
preconnection
. Furthermore it is required when trying to establish a connection with a remote endpoint withinitiate()
.-
with_address
(address)¶ This function sets the address desired to use with the local endpoint.
- Parameters
address (
str
) – The address to set.- Return type
None
-
with_hostname
(hostname)¶ This function sets the hostname for the remote endpoint.
- Parameters
hostname (
str
) – The hostname to set.- Return type
None
-
with_interface
(interface)¶ This function sets the interface desired to with the local endpoint.
- Parameters
interface (
str
) – The endpoint to set.- Return type
None
-
with_port
(port_number)¶ This function sets the port desired to use with the local endpoint.
- Parameters
port_number (
int
) – The port to set.- Return type
None
-
Framer¶
-
class
Framer
¶ -
abstract
handle_received_data
(connection)¶ Upon receiving this event, the framer implementation can inspect the inbound data. The data is parsed from a particular cursor representing the unprocessed data. The application requests a specific amount of data it needs to have available in order to parse. If the data is not available, the parse fails.
- Parameters
connection – The connection the framer is registered with.
-
abstract
new_sent_message
(connection, message_data, message_context, sent_handler, is_end_of_message)¶ Upon receiving this event, a framer implementation is responsible for performing any necessary transformations and sending the resulting data back to the Message Framer, which will in turn send it to the next protocol.
:param connection:The connection the framer is registered with. :type message_data:
bytearray
:param message_data: The data to send. :param message_context: Additionalmessage_properties
can be sent by adding them to a Message Context object Optinoal. :type sent_handler:Callable
[[Connection
,SendErrorReason
],None
] :param sent_handler: A function that is called after completion / error. :param end_of_message: When set to false indicates a partial send.
-
abstract
start
(connection)¶ When a Message Framer generates a Start event, the framer implementation has the opportunity to start writing some data prior to the Connection delivering its Ready event. This allows the implementation to communicate control data to the remote endpoint that can be used to parse Messages.
- Parameters
connection – The connection that the framer is registered with.
-
abstract
-
class
ExampleFramer
¶ To provide an example this class implements the abstract interface in
framer
class. It’s a simple TLV framer that frame TCP messages by prepending message size. This is then parsed by the same framer at the destination.To use the framer, simply create an instance, and pass it to a
preconnection
like so:new_preconnection = Preconnection(remote_endpoint=ep) preconnection.add_framer(framer.ExampleFramer())