openstack
/
deb-python-autobahn
Code Issues Proposed changes

polish docs

This commit is contained in:
Tobias Oberstein 2017-03-26 12:54:13 +02:00
parent eb22576bb2
commit b6e0342a30
13 changed files with 523 additions and 423 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
autobahn/asyncio/websocket.py
View File

@ -197,6 +197,8 @@ class WebSocketAdapterProtocol(asyncio.Protocol):
class WebSocketServerProtocol(WebSocketAdapterProtocol, protocol.WebSocketServerProtocol):
"""
Base class for asyncio-based WebSocket server protocols.
Implements :class:`autobahn.websocket.interfaces.IWebSocketChannel`.
"""
log = txaio.make_logger()
@ -206,6 +208,8 @@ class WebSocketServerProtocol(WebSocketAdapterProtocol, protocol.WebSocketServer
class WebSocketClientProtocol(WebSocketAdapterProtocol, protocol.WebSocketClientProtocol):
"""
Base class for asyncio-based WebSocket client protocols.
Implements :class:`autobahn.websocket.interfaces.IWebSocketChannel`.
"""
log = txaio.make_logger()
@ -235,16 +239,19 @@ class WebSocketAdapterFactory(object):
class WebSocketServerFactory(WebSocketAdapterFactory, protocol.WebSocketServerFactory):
"""
Base class for asyncio-based WebSocket server factories.
Implements :class:`autobahn.websocket.interfaces.IWebSocketServerChannelFactory`
"""
protocol = WebSocketServerProtocol
def __init__(self, *args, **kwargs):
"""
In addition to all arguments to the constructor of
:class:`autobahn.websocket.protocol.WebSocketServerFactory`,
you can supply a ``loop`` keyword argument to specify the
asyncio event loop to be used.
.. note::
In addition to all arguments to the constructor of
:meth:`autobahn.websocket.interfaces.IWebSocketServerChannelFactory`,
you can supply a ``loop`` keyword argument to specify the
asyncio event loop to be used.
"""
loop = kwargs.pop('loop', None)
self.loop = loop or asyncio.get_event_loop()
@ -255,15 +262,19 @@ class WebSocketServerFactory(WebSocketAdapterFactory, protocol.WebSocketServerFa
@public
class WebSocketClientFactory(WebSocketAdapterFactory, protocol.WebSocketClientFactory):
"""
Base class for asyncio-baseed WebSocket client factories.
Base class for asyncio-based WebSocket client factories.
Implements :class:`autobahn.websocket.interfaces.IWebSocketClientChannelFactory`
"""
def __init__(self, *args, **kwargs):
"""
In addition to all arguments to the constructor of
:class:`autobahn.websocket.protocol.WebSocketClientFactory`,
you can supply a ``loop`` keyword argument to specify the
asyncio event loop to be used.
.. note::
In addition to all arguments to the constructor of
:meth:`autobahn.websocket.interfaces.IWebSocketClientChannelFactory`,
you can supply a ``loop`` keyword argument to specify the
asyncio event loop to be used.
"""
loop = kwargs.pop('loop', None)
self.loop = loop or asyncio.get_event_loop()

3
autobahn/twisted/rawsocket.py
View File

@ -172,6 +172,7 @@ class WampRawSocketProtocol(Int32StringReceiver):
raise TransportLost()
@public
class WampRawSocketServerProtocol(WampRawSocketProtocol):
"""
Base class for Twisted-based WAMP-over-RawSocket server protocols.
@ -350,6 +351,7 @@ class WampRawSocketFactory(Factory):
"""
@public
class WampRawSocketServerFactory(WampRawSocketFactory):
"""
Base class for Twisted-based WAMP-over-RawSocket server factories.
@ -415,6 +417,7 @@ class WampRawSocketServerFactory(WampRawSocketFactory):
self._serializers[ser.RAWSOCKET_SERIALIZER_ID] = ser
@public
class WampRawSocketClientFactory(WampRawSocketFactory):
"""
Base class for Twisted-based WAMP-over-RawSocket client factories.

39
autobahn/twisted/websocket.py
View File

@ -38,6 +38,7 @@ from twisted.internet.interfaces import ITransport
from twisted.internet.error import ConnectionDone, ConnectionAborted, \
ConnectionLost
from autobahn.util import public
from autobahn.wamp import websocket
from autobahn.websocket.types import ConnectionRequest, ConnectionResponse, ConnectionDeny
from autobahn.websocket import protocol
@ -181,9 +182,12 @@ class WebSocketAdapterProtocol(twisted.internet.protocol.Protocol):
self.transport.registerProducer(producer, streaming)
@public
class WebSocketServerProtocol(WebSocketAdapterProtocol, protocol.WebSocketServerProtocol):
"""
Base class for Twisted-based WebSocket server protocols.
Implements :class:`autobahn.websocket.interfaces.IWebSocketChannel`.
"""
log = txaio.make_logger()
@ -195,9 +199,12 @@ class WebSocketServerProtocol(WebSocketAdapterProtocol, protocol.WebSocketServer
return transport_channel_id(self.transport, is_server=True, channel_id_type=channel_id_type)
@public
class WebSocketClientProtocol(WebSocketAdapterProtocol, protocol.WebSocketClientProtocol):
"""
Base class for Twisted-based WebSocket client protocols.
Implements :class:`autobahn.websocket.interfaces.IWebSocketChannel`.
"""
log = txaio.make_logger()
@ -222,17 +229,22 @@ class WebSocketAdapterFactory(object):
"""
@public
class WebSocketServerFactory(WebSocketAdapterFactory, protocol.WebSocketServerFactory, twisted.internet.protocol.ServerFactory):
"""
Base class for Twisted-based WebSocket server factories.
Implements :class:`autobahn.websocket.interfaces.IWebSocketServerChannelFactory`
"""
def __init__(self, *args, **kwargs):
"""
In addition to all arguments to the constructor of
:class:`autobahn.websocket.protocol.WebSocketServerFactory`,
you can supply a `reactor` keyword argument to specify the
Twisted reactor to be used.
.. note::
In addition to all arguments to the constructor of
:meth:`autobahn.websocket.interfaces.IWebSocketServerChannelFactory`,
you can supply a ``reactor`` keyword argument to specify the
Twisted reactor to be used.
"""
# lazy import to avoid reactor install upon module import
reactor = kwargs.pop('reactor', None)
@ -243,17 +255,22 @@ class WebSocketServerFactory(WebSocketAdapterFactory, protocol.WebSocketServerFa
protocol.WebSocketServerFactory.__init__(self, *args, **kwargs)
@public
class WebSocketClientFactory(WebSocketAdapterFactory, protocol.WebSocketClientFactory, twisted.internet.protocol.ClientFactory):
"""
Base class for Twisted-based WebSocket client factories.
Implements :class:`autobahn.websocket.interfaces.IWebSocketClientChannelFactory`
"""
def __init__(self, *args, **kwargs):
"""
In addition to all arguments to the constructor of
:class:`autobahn.websocket.protocol.WebSocketClientFactory`,
you can supply a `reactor` keyword argument to specify the
Twisted reactor to be used.
.. note::
In addition to all arguments to the constructor of
:func:`autobahn.websocket.interfaces.IWebSocketClientChannelFactory`,
you can supply a ``reactor`` keyword argument to specify the
Twisted reactor to be used.
"""
# lazy import to avoid reactor install upon module import
reactor = kwargs.pop('reactor', None)
@ -481,6 +498,7 @@ class WrappingWebSocketClientFactory(WebSocketClientFactory):
return proto
@public
def connectWS(factory, contextFactory=None, timeout=30, bindAddress=None):
"""
Establish WebSocket connection to a server. The connection parameters like target
@ -521,6 +539,7 @@ def connectWS(factory, contextFactory=None, timeout=30, bindAddress=None):
return conn
@public
def listenWS(factory, contextFactory=None, backlog=50, interface=''):
"""
Listen for incoming WebSocket connections from clients. The connection parameters like
@ -553,12 +572,14 @@ def listenWS(factory, contextFactory=None, backlog=50, interface=''):
return listener
@public
class WampWebSocketServerProtocol(websocket.WampWebSocketServerProtocol, WebSocketServerProtocol):
"""
Base class for Twisted-based WAMP-over-WebSocket server protocols.
"""
@public
class WampWebSocketServerFactory(websocket.WampWebSocketServerFactory, WebSocketServerFactory):
"""
Base class for Twisted-based WAMP-over-WebSocket server factories.
@ -578,12 +599,14 @@ class WampWebSocketServerFactory(websocket.WampWebSocketServerFactory, WebSocket
WebSocketServerFactory.__init__(self, *args, **kwargs)
@public
class WampWebSocketClientProtocol(websocket.WampWebSocketClientProtocol, WebSocketClientProtocol):
"""
Base class for Twisted-based WAMP-over-WebSocket client protocols.
"""
@public
class WampWebSocketClientFactory(websocket.WampWebSocketClientFactory, WebSocketClientFactory):
"""
Base class for Twisted-based WAMP-over-WebSocket client factories.

399
autobahn/websocket/interfaces.py
View File

@ -29,11 +29,352 @@ import six
from autobahn.util import public
__all__ = ('IWebSocketChannel',
__all__ = ('IWebSocketServerChannelFactory',
'IWebSocketClientChannelFactory',
'IWebSocketChannel',
'IWebSocketChannelFrameApi',
'IWebSocketChannelStreamingApi')
@public
@six.add_metaclass(abc.ABCMeta)
class IWebSocketServerChannelFactory(object):
"""
WebSocket server protocol factories implement this interface, and create
protocol instances which in turn implement
:class:`autobahn.websocket.interfaces.IWebSocketChannel`.
"""
@abc.abstractmethod
def __init__(url=None,
protocols=None,
server=None,
headers=None,
externalPort=None):
"""
:param url: The WebSocket URL this factory is working for, e.g. ``ws://myhost.com/somepath``.
For non-TCP transports like pipes or Unix domain sockets, provide ``None``.
This will use an implicit URL of ``ws://localhost``.
:type url: str
:param protocols: List of subprotocols the server supports. The subprotocol used is the first from the list of subprotocols announced by the client that is contained in this list.
:type protocols: list of str
:param server: Server as announced in HTTP response header during opening handshake.
:type server: str
:param headers: An optional mapping of additional HTTP headers to send during the WebSocket opening handshake.
:type headers: dict
:param externalPort: Optionally, the external visible port this server will be reachable under (i.e. when running behind a L2/L3 forwarding device).
:type externalPort: int
"""
@public
@abc.abstractmethod
def setSessionParameters(url=None,
protocols=None,
server=None,
headers=None,
externalPort=None):
"""
Set WebSocket session parameters.
:param url: The WebSocket URL this factory is working for, e.g. ``ws://myhost.com/somepath``.
For non-TCP transports like pipes or Unix domain sockets, provide ``None``.
This will use an implicit URL of ``ws://localhost``.
:type url: str
:param protocols: List of subprotocols the server supports. The subprotocol used is the first from the list of subprotocols announced by the client that is contained in this list.
:type protocols: list of str
:param server: Server as announced in HTTP response header during opening handshake.
:type server: str
:param headers: An optional mapping of additional HTTP headers to send during the WebSocket opening handshake.
:type headers: dict
:param externalPort: Optionally, the external visible port this server will be reachable under (i.e. when running behind a L2/L3 forwarding device).
:type externalPort: int
"""
@public
@abc.abstractmethod
def setProtocolOptions(versions=None,
webStatus=None,
utf8validateIncoming=None,
maskServerFrames=None,
requireMaskedClientFrames=None,
applyMask=None,
maxFramePayloadSize=None,
maxMessagePayloadSize=None,
autoFragmentSize=None,
failByDrop=None,
echoCloseCodeReason=None,
openHandshakeTimeout=None,
closeHandshakeTimeout=None,
tcpNoDelay=None,
perMessageCompressionAccept=None,
autoPingInterval=None,
autoPingTimeout=None,
autoPingSize=None,
serveFlashSocketPolicy=None,
flashSocketPolicy=None,
allowedOrigins=None,
allowNullOrigin=False,
maxConnections=None):
"""
Set WebSocket protocol options used as defaults for new protocol instances.
:param versions: The WebSocket protocol versions accepted by the server (default: :func:`autobahn.websocket.protocol.WebSocketProtocol.SUPPORTED_PROTOCOL_VERSIONS`).
:type versions: list of ints or None
:param webStatus: Return server status/version on HTTP/GET without WebSocket upgrade header (default: `True`).
:type webStatus: bool or None
:param utf8validateIncoming: Validate incoming UTF-8 in text message payloads (default: `True`).
:type utf8validateIncoming: bool or None
:param maskServerFrames: Mask server-to-client frames (default: `False`).
:type maskServerFrames: bool or None
:param requireMaskedClientFrames: Require client-to-server frames to be masked (default: `True`).
:type requireMaskedClientFrames: bool or None
:param applyMask: Actually apply mask to payload when mask it present. Applies for outgoing and incoming frames (default: `True`).
:type applyMask: bool or None
:param maxFramePayloadSize: Maximum frame payload size that will be accepted when receiving or `0` for unlimited (default: `0`).
:type maxFramePayloadSize: int or None
:param maxMessagePayloadSize: Maximum message payload size (after reassembly of fragmented messages) that will be accepted when receiving or `0` for unlimited (default: `0`).
:type maxMessagePayloadSize: int or None
:param autoFragmentSize: Automatic fragmentation of outgoing data messages (when using the message-based API) into frames with payload length `<=` this size or `0` for no auto-fragmentation (default: `0`).
:type autoFragmentSize: int or None
:param failByDrop: Fail connections by dropping the TCP connection without performing closing handshake (default: `True`).
:type failbyDrop: bool or None
:param echoCloseCodeReason: Iff true, when receiving a close, echo back close code/reason. Otherwise reply with `code == 1000, reason = ""` (default: `False`).
:type echoCloseCodeReason: bool or None
:param openHandshakeTimeout: Opening WebSocket handshake timeout, timeout in seconds or `0` to deactivate (default: `0`).
:type openHandshakeTimeout: float or None
:param closeHandshakeTimeout: When we expect to receive a closing handshake reply, timeout in seconds (default: `1`).
:type closeHandshakeTimeout: float or None
:param tcpNoDelay: TCP NODELAY ("Nagle") socket option (default: `True`).
:type tcpNoDelay: bool or None
:param perMessageCompressionAccept: Acceptor function for offers.
:type perMessageCompressionAccept: callable or None
:param autoPingInterval: Automatically send WebSocket pings every given seconds. When the peer does not respond
in `autoPingTimeout`, drop the connection. Set to `0` to disable. (default: `0`).
:type autoPingInterval: float or None
:param autoPingTimeout: Wait this many seconds for the peer to respond to automatically sent pings. If the
peer does not respond in time, drop the connection. Set to `0` to disable. (default: `0`).
:type autoPingTimeout: float or None
:param autoPingSize: Payload size for automatic pings/pongs. Must be an integer from `[4, 125]`. (default: `4`).
:type autoPingSize: int or None
:param serveFlashSocketPolicy: Serve the Flash Socket Policy when we receive a policy file request on this protocol. (default: `False`).
:type serveFlashSocketPolicy: bool or None
:param flashSocketPolicy: The flash socket policy to be served when we are serving the Flash Socket Policy on this protocol
and when Flash tried to connect to the destination port. It must end with a null character.
:type flashSocketPolicy: str or None
:param allowedOrigins: A list of allowed WebSocket origins (with '*' as a wildcard character).
:type allowedOrigins: list or None
:param allowNullOrigin: if True, allow WebSocket connections whose `Origin:` is `"null"`.
:type allowNullOrigin: bool
:param maxConnections: Maximum number of concurrent connections. Set to `0` to disable (default: `0`).
:type maxConnections: int or None
"""
@public
@abc.abstractmethod
def resetProtocolOptions(self):
"""
Reset all WebSocket protocol options to defaults.
"""
@public
@six.add_metaclass(abc.ABCMeta)
class IWebSocketClientChannelFactory(object):
"""
WebSocket client protocol factories implement this interface, and create
protocol instances which in turn implement
:class:`autobahn.websocket.interfaces.IWebSocketChannel`.
"""
@abc.abstractmethod
def __init__(url=None,
origin=None,
protocols=None,
useragent=None,
headers=None,
proxy=None):
"""
Note that you MUST provide URL either here or set using
:meth:`autobahn.websocket.WebSocketClientFactory.setSessionParameters`
*before* the factory is started.
:param url: WebSocket URL this factory will connect to, e.g. ``ws://myhost.com/somepath?param1=23``.
For non-TCP transports like pipes or Unix domain sockets, provide ``None``.
This will use an implicit URL of ``ws://localhost``.
:type url: str
:param origin: The origin to be sent in WebSocket opening handshake or None (default: `None`).
:type origin: str
:param protocols: List of subprotocols the client should announce in WebSocket opening handshake (default: `[]`).
:type protocols: list of strings
:param useragent: User agent as announced in HTTP request header or None (default: `AutobahnWebSocket/?.?.?`).
:type useragent: str
:param headers: An optional mapping of additional HTTP headers to send during the WebSocket opening handshake.
:type headers: dict
:param proxy: Explicit proxy server to use; a dict with ``host`` and ``port`` keys
:type proxy: dict or None
"""
@public
@abc.abstractmethod
def setSessionParameters(url=None,
origin=None,
protocols=None,
useragent=None,
headers=None,
proxy=None):
"""
Set WebSocket session parameters.
:param url: WebSocket URL this factory will connect to, e.g. `ws://myhost.com/somepath?param1=23`.
For non-TCP transports like pipes or Unix domain sockets, provide `None`.
This will use an implicit URL of `ws://localhost`.
:type url: str
:param origin: The origin to be sent in opening handshake.
:type origin: str
:param protocols: List of WebSocket subprotocols the client should announce in opening handshake.
:type protocols: list of strings
:param useragent: User agent as announced in HTTP request header during opening handshake.
:type useragent: str
:param headers: An optional mapping of additional HTTP headers to send during the WebSocket opening handshake.
:type headers: dict
:param proxy: (Optional) a dict with ``host`` and ``port`` keys specifying a proxy to use
:type proxy: dict or None
"""
@public
@abc.abstractmethod
def setProtocolOptions(version=None,
utf8validateIncoming=None,
acceptMaskedServerFrames=None,
maskClientFrames=None,
applyMask=None,
maxFramePayloadSize=None,
maxMessagePayloadSize=None,
autoFragmentSize=None,
failByDrop=None,
echoCloseCodeReason=None,
serverConnectionDropTimeout=None,
openHandshakeTimeout=None,
closeHandshakeTimeout=None,
tcpNoDelay=None,
perMessageCompressionOffers=None,
perMessageCompressionAccept=None,
autoPingInterval=None,
autoPingTimeout=None,
autoPingSize=None):
"""
Set WebSocket protocol options used as defaults for _new_ protocol instances.
:param version: The WebSocket protocol spec (draft) version to be used (default: :func:`autobahn.websocket.protocol.WebSocketProtocol.SUPPORTED_PROTOCOL_VERSIONS`).
:type version: int
:param utf8validateIncoming: Validate incoming UTF-8 in text message payloads (default: `True`).
:type utf8validateIncoming: bool
:param acceptMaskedServerFrames: Accept masked server-to-client frames (default: `False`).
:type acceptMaskedServerFrames: bool
:param maskClientFrames: Mask client-to-server frames (default: `True`).
:type maskClientFrames: bool
:param applyMask: Actually apply mask to payload when mask it present. Applies for outgoing and incoming frames (default: `True`).
:type applyMask: bool
:param maxFramePayloadSize: Maximum frame payload size that will be accepted when receiving or `0` for unlimited (default: `0`).
:type maxFramePayloadSize: int
:param maxMessagePayloadSize: Maximum message payload size (after reassembly of fragmented messages) that will be accepted when receiving or `0` for unlimited (default: `0`).
:type maxMessagePayloadSize: int
:param autoFragmentSize: Automatic fragmentation of outgoing data messages (when using the message-based API) into frames with payload length `<=` this size or `0` for no auto-fragmentation (default: `0`).
:type autoFragmentSize: int
:param failByDrop: Fail connections by dropping the TCP connection without performing closing handshake (default: `True`).
:type failbyDrop: bool
:param echoCloseCodeReason: Iff true, when receiving a close, echo back close code/reason. Otherwise reply with `code == 1000, reason = ""` (default: `False`).
:type echoCloseCodeReason: bool
:param serverConnectionDropTimeout: When the client expects the server to drop the TCP, timeout in seconds (default: `1`).
:type serverConnectionDropTimeout: float
:param openHandshakeTimeout: Opening WebSocket handshake timeout, timeout in seconds or `0` to deactivate (default: `0`).
:type openHandshakeTimeout: float
:param closeHandshakeTimeout: When we expect to receive a closing handshake reply, timeout in seconds (default: `1`).
:type closeHandshakeTimeout: float
:param tcpNoDelay: TCP NODELAY ("Nagle"): bool socket option (default: `True`).
:type tcpNoDelay: bool
:param perMessageCompressionOffers: A list of offers to provide to the server for the permessage-compress WebSocket extension. Must be a list of instances of subclass of PerMessageCompressOffer.
:type perMessageCompressionOffers: list of instance of subclass of PerMessageCompressOffer
:param perMessageCompressionAccept: Acceptor function for responses.
:type perMessageCompressionAccept: callable
:param autoPingInterval: Automatically send WebSocket pings every given seconds. When the peer does not respond
in `autoPingTimeout`, drop the connection. Set to `0` to disable. (default: `0`).
:type autoPingInterval: float or None
:param autoPingTimeout: Wait this many seconds for the peer to respond to automatically sent pings. If the
peer does not respond in time, drop the connection. Set to `0` to disable. (default: `0`).
:type autoPingTimeout: float or None
:param autoPingSize: Payload size for automatic pings/pongs. Must be an integer from `[4, 125]`. (default: `4`).
:type autoPingSize: int
"""
@public
@abc.abstractmethod
def resetProtocolOptions(self):
"""
Reset all WebSocket protocol options to defaults.
"""
@public
@six.add_metaclass(abc.ABCMeta)
class IWebSocketChannel(object):
@ -47,7 +388,7 @@ class IWebSocketChannel(object):
@public
@abc.abstractmethod
def on_connect(self, request_or_response):
def onConnect(self, request_or_response):
"""
Callback fired during WebSocket opening handshake when a client connects (to a server with
request from client) or when server connection established (by a client with response from
@ -68,7 +409,7 @@ class IWebSocketChannel(object):
@public
@abc.abstractmethod
def on_open(self):
def onOpen(self):
"""
Callback fired when the initial WebSocket opening handshake was completed.
You now can send and receive WebSocket messages.
@ -76,27 +417,35 @@ class IWebSocketChannel(object):
@public
@abc.abstractmethod
def send_message(self, message):
def sendMessage(self, payload, isBinary):
"""
Send a WebSocket message over the connection to the peer.
:param message: The WebSocket message to be sent.
:type message: Instance of :class:`autobahn.websocket.types.OutgoingMessage`
:param payload: The WebSocket message to be sent.
:type payload: bytes
:param isBinary: Flag indicating whether payload is binary or
UTF-8 encoded text.
:type isBinary: bool
"""
@public
@abc.abstractmethod
def on_message(self, message):
def onMessage(self, payload, isBinary):
"""
Callback fired when a complete WebSocket message was received.
:param message: The WebSocket message received.
:type message: :class:`autobahn.websocket.types.IncomingMessage`
:param payload: The WebSocket message received.
:type payload: bytes
:param isBinary: Flag indicating whether payload is binary or
UTF-8 encoded text.
:type isBinary: bool
"""
@public
@abc.abstractmethod
def send_close(self, code=None, reason=None):
def sendClose(self, code=None, reason=None):
"""
Starts a WebSocket closing handshake tearing down the WebSocket connection.
@ -105,37 +454,28 @@ class IWebSocketChannel(object):
:type code: int
:param reason: An optional close reason (a string that when present, a status
code MUST also be present).
:type reason: unicode
:type reason: str
"""
@public
@abc.abstractmethod
def on_close(self, was_clean, code, reason):
def onClose(self, wasClean, code, reason):
"""
Callback fired when the WebSocket connection has been closed (WebSocket closing
handshake has been finished or the connection was closed uncleanly).
:param wasClean: ``True`` iff the WebSocket connection was closed cleanly.
:type wasClean: bool
:param code: Close status code as sent by the WebSocket peer.
:type code: int or None
:param reason: Close reason as sent by the WebSocket peer.
:type reason: unicode or None
:type reason: str or None
"""
@public
@abc.abstractmethod
def sendPreparedMessage(self, preparedMsg):
"""
Send a message that was previously prepared with :func:`autobahn.websocket.protocol.WebSocketFactory.prepareMessage`.
:param prepareMessage: A previously prepared message.
:type prepareMessage: Instance of :class:`autobahn.websocket.protocol.PreparedMessage`.
"""
@public
@abc.abstractmethod
def send_ping(self, payload=None):
def sendPing(self, payload=None):
"""
Send a WebSocket ping to the peer.
@ -146,9 +486,8 @@ class IWebSocketChannel(object):
:type payload: bytes or None
"""
@public
@abc.abstractmethod
def on_ping(self, payload):
def onPing(self, payload):
"""
Callback fired when a WebSocket ping was received. A default implementation responds
by sending a WebSocket pong.
@ -157,9 +496,8 @@ class IWebSocketChannel(object):
:type payload: bytes
"""
@public
@abc.abstractmethod
def send_pong(self, payload=None):
def sendPong(self, payload=None):
"""
Send a WebSocket pong to the peer.
@ -170,9 +508,8 @@ class IWebSocketChannel(object):
:type payload: bytes
"""
@public
@abc.abstractmethod
def on_pong(self, payload):
def onPong(self, payload):
"""
Callback fired when a WebSocket pong was received. A default implementation does nothing.

174
autobahn/websocket/protocol.py
View File

@ -3055,6 +3055,8 @@ class WebSocketServerProtocol(WebSocketProtocol):
class WebSocketServerFactory(WebSocketFactory):
"""
A protocol factory for WebSocket servers.
Implements :func:`autobahn.websocket.interfaces.IWebSocketServerChannelFactory`
"""
log = txaio.make_logger()
@ -3076,20 +3078,7 @@ class WebSocketServerFactory(WebSocketFactory):
headers=None,
externalPort=None):
"""
Create instance of WebSocket server factory.
:param url: The WebSocket URL this factory is working for, e.g. `ws://myhost.com/somepath`.
For non-TCP transports like pipes or Unix domain sockets, provide `None`.
This will use an implicit URL of `ws://localhost`.
:type url: str
:param protocols: List of subprotocols the server supports. The subprotocol used is the first from the list of subprotocols announced by the client that is contained in this list.
:type protocols: list of strings
:param server: Server as announced in HTTP response header during opening handshake or None (default: `AutobahnWebSocket/?.?.?`).
:type server: str
:param headers: An optional mapping of additional HTTP headers to send during the WebSocket opening handshake.
:type headers: dict
:param externalPort: Optionally, the external visible port this factory will be reachable under (i.e. when running behind a L2/L3 forwarding device).
:type externalPort: int
Implements :func:`autobahn.websocket.interfaces.IWebSocketServerChannelFactory.__init__`
"""
self.logOctets = False
self.logFrames = False
@ -3123,21 +3112,9 @@ class WebSocketServerFactory(WebSocketFactory):
headers=None,
externalPort=None):
"""
Set WebSocket session parameters.
:param url: The WebSocket URL this factory is working for, e.g. `ws://myhost.com/somepath`.
For non-TCP transports like pipes or Unix domain sockets, provide `None`.
This will use an implicit URL of `ws://localhost`.
:type url: str
:param protocols: List of subprotocols the server supports. The subprotocol used is the first from the list of subprotocols announced by the client that is contained in this list.
:type protocols: list of strings
:param server: Server as announced in HTTP response header during opening handshake.
:type server: str
:param headers: An optional mapping of additional HTTP headers to send during the WebSocket opening handshake.
:type headers: dict
:param externalPort: Optionally, the external visible port this server will be reachable under (i.e. when running behind a L2/L3 forwarding device).
:type externalPort: int
Implements :func:`autobahn.websocket.interfaces.IWebSocketServerChannelFactory.setSessionParameters`
"""
# parse WebSocket URI into components
(isSecure, host, port, resource, path, params) = parse_url(url or "ws://localhost")
if len(params) > 0:
@ -3163,7 +3140,7 @@ class WebSocketServerFactory(WebSocketFactory):
def resetProtocolOptions(self):
"""
Reset all WebSocket protocol options to defaults.
Implements :func:`autobahn.websocket.interfaces.IWebSocketServerChannelFactory.resetProtocolOptions`
"""
self.versions = WebSocketProtocol.SUPPORTED_PROTOCOL_VERSIONS
self.webStatus = True
@ -3227,60 +3204,7 @@ class WebSocketServerFactory(WebSocketFactory):
allowNullOrigin=False,
maxConnections=None):
"""
Set WebSocket protocol options used as defaults for new protocol instances.
:param versions: The WebSocket protocol versions accepted by the server (default: :func:`autobahn.websocket.protocol.WebSocketProtocol.SUPPORTED_PROTOCOL_VERSIONS`).
:type versions: list of ints or None
:param webStatus: Return server status/version on HTTP/GET without WebSocket upgrade header (default: `True`).
:type webStatus: bool or None
:param utf8validateIncoming: Validate incoming UTF-8 in text message payloads (default: `True`).
:type utf8validateIncoming: bool or None
:param maskServerFrames: Mask server-to-client frames (default: `False`).
:type maskServerFrames: bool or None
:param requireMaskedClientFrames: Require client-to-server frames to be masked (default: `True`).
:type requireMaskedClientFrames: bool or None
:param applyMask: Actually apply mask to payload when mask it present. Applies for outgoing and incoming frames (default: `True`).
:type applyMask: bool or None
:param maxFramePayloadSize: Maximum frame payload size that will be accepted when receiving or `0` for unlimited (default: `0`).
:type maxFramePayloadSize: int or None
:param maxMessagePayloadSize: Maximum message payload size (after reassembly of fragmented messages) that will be accepted when receiving or `0` for unlimited (default: `0`).
:type maxMessagePayloadSize: int or None
:param autoFragmentSize: Automatic fragmentation of outgoing data messages (when using the message-based API) into frames with payload length `<=` this size or `0` for no auto-fragmentation (default: `0`).
:type autoFragmentSize: int or None
:param failByDrop: Fail connections by dropping the TCP connection without performing closing handshake (default: `True`).
:type failbyDrop: bool or None
:param echoCloseCodeReason: Iff true, when receiving a close, echo back close code/reason. Otherwise reply with `code == 1000, reason = ""` (default: `False`).
:type echoCloseCodeReason: bool or None
:param openHandshakeTimeout: Opening WebSocket handshake timeout, timeout in seconds or `0` to deactivate (default: `0`).
:type openHandshakeTimeout: float or None
:param closeHandshakeTimeout: When we expect to receive a closing handshake reply, timeout in seconds (default: `1`).
:type closeHandshakeTimeout: float or None
:param tcpNoDelay: TCP NODELAY ("Nagle") socket option (default: `True`).
:type tcpNoDelay: bool or None
:param perMessageCompressionAccept: Acceptor function for offers.
:type perMessageCompressionAccept: callable or None
:param autoPingInterval: Automatically send WebSocket pings every given seconds. When the peer does not respond
in `autoPingTimeout`, drop the connection. Set to `0` to disable. (default: `0`).
:type autoPingInterval: float or None
:param autoPingTimeout: Wait this many seconds for the peer to respond to automatically sent pings. If the
peer does not respond in time, drop the connection. Set to `0` to disable. (default: `0`).
:type autoPingTimeout: float or None
:param autoPingSize: Payload size for automatic pings/pongs. Must be an integer from `[4, 125]`. (default: `4`).
:type autoPingSize: int or None
:param serveFlashSocketPolicy: Serve the Flash Socket Policy when we receive a policy file request on this protocol. (default: `False`).
:type serveFlashSocketPolicy: bool or None
:param flashSocketPolicy: The flash socket policy to be served when we are serving the Flash Socket Policy on this protocol
and when Flash tried to connect to the destination port. It must end with a null character.
:type flashSocketPolicy: str or None
:param allowedOrigins: A list of allowed WebSocket origins (with '*' as a wildcard character).
:type allowedOrigins: list or None
:param allowNullOrigin: if True, allow WebSocket connections whose `Origin:` is `"null"`.
:type allowNullOrigin: bool
:param maxConnections: Maximum number of concurrent connections. Set to `0` to disable (default: `0`).
:type maxConnections: int or None
Implements :func:`autobahn.websocket.interfaces.IWebSocketServerChannelFactory.setProtocolOptions`
"""
if versions is not None:
for v in versions:
@ -3823,6 +3747,8 @@ class WebSocketClientProtocol(WebSocketProtocol):
class WebSocketClientFactory(WebSocketFactory):
"""
A protocol factory for WebSocket clients.
Implements :func:`autobahn.websocket.interfaces.IWebSocketClientChannelFactory`
"""
log = txaio.make_logger()
@ -3845,26 +3771,7 @@ class WebSocketClientFactory(WebSocketFactory):
headers=None,
proxy=None):
"""
Create instance of WebSocket client factory.
Note that you MUST provide URL either here or set using
:meth:`autobahn.websocket.WebSocketClientFactory.setSessionParameters`
*before* the factory is started.
:param url: WebSocket URL this factory will connect to, e.g. `ws://myhost.com/somepath?param1=23`.
For non-TCP transports like pipes or Unix domain sockets, provide `None`.
This will use an implicit URL of `ws://localhost`.
:type url: str
:param origin: The origin to be sent in WebSocket opening handshake or None (default: `None`).
:type origin: str
:param protocols: List of subprotocols the client should announce in WebSocket opening handshake (default: `[]`).
:type protocols: list of strings
:param useragent: User agent as announced in HTTP request header or None (default: `AutobahnWebSocket/?.?.?`).
:type useragent: str
:param headers: An optional mapping of additional HTTP headers to send during the WebSocket opening handshake.
:type headers: dict
:param proxy: Explicit proxy server to use; a dict with ``host`` and ``port`` keys
:type proxy: dict or None
Implements :func:`autobahn.websocket.interfaces.IWebSocketClientChannelFactory.__init__`
"""
self.logOctets = False
self.logFrames = False
@ -3895,22 +3802,7 @@ class WebSocketClientFactory(WebSocketFactory):
headers=None,
proxy=None):
"""
Set WebSocket session parameters.
:param url: WebSocket URL this factory will connect to, e.g. `ws://myhost.com/somepath?param1=23`.
For non-TCP transports like pipes or Unix domain sockets, provide `None`.
This will use an implicit URL of `ws://localhost`.
:type url: str
:param origin: The origin to be sent in opening handshake.
:type origin: str
:param protocols: List of WebSocket subprotocols the client should announce in opening handshake.
:type protocols: list of strings
:param useragent: User agent as announced in HTTP request header during opening handshake.
:type useragent: str
:param headers: An optional mapping of additional HTTP headers to send during the WebSocket opening handshake.
:type headers: dict
:param proxy: (Optional) a dict with ``host`` and ``port`` keys specifying a proxy to use
:type proxy: dict or None
Implements :func:`autobahn.websocket.interfaces.IWebSocketClientChannelFactory.setSessionParameters`
"""
# parse WebSocket URI into components
(isSecure, host, port, resource, path, params) = parse_url(url or "ws://localhost")
@ -3931,7 +3823,7 @@ class WebSocketClientFactory(WebSocketFactory):
def resetProtocolOptions(self):
"""
Reset all WebSocket protocol options to defaults.
Implements :func:`autobahn.websocket.interfaces.IWebSocketClientChannelFactory.resetProtocolOptions`
"""
self.version = WebSocketProtocol.DEFAULT_SPEC_VERSION
self.utf8validateIncoming = True
@ -3980,47 +3872,7 @@ class WebSocketClientFactory(WebSocketFactory):
autoPingTimeout=None,
autoPingSize=None):
"""
Set WebSocket protocol options used as defaults for _new_ protocol instances.
:param version: The WebSocket protocol spec (draft) version to be used (default: :func:`autobahn.websocket.protocol.WebSocketProtocol.SUPPORTED_PROTOCOL_VERSIONS`).
:param utf8validateIncoming: Validate incoming UTF-8 in text message payloads (default: `True`).
:type utf8validateIncoming: bool
:param acceptMaskedServerFrames: Accept masked server-to-client frames (default: `False`).
:type acceptMaskedServerFrames: bool
:param maskClientFrames: Mask client-to-server frames (default: `True`).
:type maskClientFrames: bool
:param applyMask: Actually apply mask to payload when mask it present. Applies for outgoing and incoming frames (default: `True`).
:type applyMask: bool
:param maxFramePayloadSize: Maximum frame payload size that will be accepted when receiving or `0` for unlimited (default: `0`).
:type maxFramePayloadSize: int
:param maxMessagePayloadSize: Maximum message payload size (after reassembly of fragmented messages) that will be accepted when receiving or `0` for unlimited (default: `0`).
:type maxMessagePayloadSize: int
:param autoFragmentSize: Automatic fragmentation of outgoing data messages (when using the message-based API) into frames with payload length `<=` this size or `0` for no auto-fragmentation (default: `0`).
:type autoFragmentSize: int
:param failByDrop: Fail connections by dropping the TCP connection without performing closing handshake (default: `True`).
:type failbyDrop: bool
:param echoCloseCodeReason: Iff true, when receiving a close, echo back close code/reason. Otherwise reply with `code == 1000, reason = ""` (default: `False`).
:type echoCloseCodeReason: bool
:param serverConnectionDropTimeout: When the client expects the server to drop the TCP, timeout in seconds (default: `1`).
:type serverConnectionDropTimeout: float
:param openHandshakeTimeout: Opening WebSocket handshake timeout, timeout in seconds or `0` to deactivate (default: `0`).
:type openHandshakeTimeout: float
:param closeHandshakeTimeout: When we expect to receive a closing handshake reply, timeout in seconds (default: `1`).
:type closeHandshakeTimeout: float
:param tcpNoDelay: TCP NODELAY ("Nagle"): bool socket option (default: `True`).
:type tcpNoDelay: bool
:param perMessageCompressionOffers: A list of offers to provide to the server for the permessage-compress WebSocket extension. Must be a list of instances of subclass of PerMessageCompressOffer.
:type perMessageCompressionOffers: list of instance of subclass of PerMessageCompressOffer
:param perMessageCompressionAccept: Acceptor function for responses.
:type perMessageCompressionAccept: callable
:param autoPingInterval: Automatically send WebSocket pings every given seconds. When the peer does not respond
in `autoPingTimeout`, drop the connection. Set to `0` to disable. (default: `0`).
:type autoPingInterval: float or None
:param autoPingTimeout: Wait this many seconds for the peer to respond to automatically sent pings. If the
peer does not respond in time, drop the connection. Set to `0` to disable. (default: `0`).
:type autoPingTimeout: float or None
:param autoPingSize: Payload size for automatic pings/pongs. Must be an integer from `[4, 125]`. (default: `4`).
:type autoPingSize: int
Implements :func:`autobahn.websocket.interfaces.IWebSocketClientChannelFactory.setProtocolOptions`
"""
if version is not None:
if version not in WebSocketProtocol.SUPPORTED_SPEC_VERSIONS:

4
autobahn/websocket/types.py
View File

@ -283,7 +283,6 @@ class ConnectionDeny(Exception):
self.reason = reason
@public
class Message(object):
"""
Abstract base class for WebSocket messages.
@ -292,7 +291,6 @@ class Message(object):
__slots__ = ()
@public
class IncomingMessage(Message):
"""
An incoming WebSocket message.
@ -318,7 +316,6 @@ class IncomingMessage(Message):
self.is_binary = is_binary
@public
class OutgoingMessage(Message):
"""
An outgoing WebSocket message.
@ -352,7 +349,6 @@ class OutgoingMessage(Message):
self.skip_compress = skip_compress
@public
class Ping(object):
"""
A WebSocket ping message.

4
autobahn/websocket/util.py
View File

@ -26,6 +26,8 @@
from __future__ import absolute_import
from autobahn.util import public
import six
from six.moves import urllib
# The Python urlparse module currently does not contain the ws/wss
@ -56,6 +58,7 @@ __all__ = (
)
@public
def create_url(hostname, port=None, isSecure=False, path=None, params=None):
"""
Create a WebSocket URL from components.
@ -103,6 +106,7 @@ def create_url(hostname, port=None, isSecure=False, path=None, params=None):
return urllib.parse.urlunparse((scheme, netloc, ppath, None, query, None))
@public
def parse_url(url):
"""
Parses as WebSocket URL into it's components and returns a tuple (isSecure, host, port, resource, path, params).

36
docs/reference/autobahn.asyncio.rst
View File

@ -1,32 +1,20 @@
autobahn.asyncio
================
Module ``autobahn.asyncio``
===========================
Autobahn asyncio specific classes. These are used when asyncio is run as the underlying networking framework.
autobahn.asyncio.wamp
---------------------
WebSocket Protocols and Factories
---------------------------------
WAMP on asyncio.
.. automodule:: autobahn.asyncio.wamp
:members:
:show-inheritance:
autobahn.asyncio.websocket
--------------------------
WebSocket on asyncio.
.. automodule:: autobahn.asyncio.websocket
.. autoclass:: autobahn.asyncio.websocket.WebSocketServerProtocol
:members:
autobahn.asyncio.rawsocket
--------------------------
RawSocket on asyncio.
.. automodule:: autobahn.asyncio.rawsocket
.. autoclass:: autobahn.asyncio.websocket.WebSocketClientProtocol
:members:
.. autoclass:: autobahn.asyncio.websocket.WebSocketServerFactory
:members:
.. autoclass:: autobahn.asyncio.websocket.WebSocketClientFactory
:members:

39
docs/reference/autobahn.rst
View File

@ -1,40 +1,17 @@
API Reference
=============
Public API Reference
====================
The following is a API reference of |Ab| generated from Python source code and docstrings.
.. warning::
This is a *complete* reference of both the *public* API and the *internal* API of |Ab|.
Applications should only rely on the *public* API, since internal APIs can (and often do) change without any guarantees.
This is a *complete* reference of the *public* API of |Ab|.
User code and applications should only rely on the *public* API, since internal APIs can (and will) change without any guarantees.
Subpackages
-----------
.. toctree::
autobahn.asyncio
autobahn.twisted
autobahn.wamp
autobahn.util
autobahn.websocket
autobahn.rawsocket
Submodules
----------
autobahn.util
-------------
.. automodule:: autobahn.util
:members:
:undoc-members:
:show-inheritance:
Module contents
---------------
.. automodule:: autobahn
:members:
:undoc-members:
:show-inheritance:
autobahn.wamp
autobahn.twisted
autobahn.asyncio

70
docs/reference/autobahn.twisted.rst
View File

@ -1,70 +1,20 @@
autobahn.twisted
================
Module ``autobahn.twisted``
===========================
Autobahn Twisted specific classes. These are used when Twisted is run as the underlying networking framework.
Submodules
----------
WebSocket Protocols and Factories
---------------------------------
autobahn.twisted.choosereactor
------------------------------
.. automodule:: autobahn.twisted.choosereactor
.. autoclass:: autobahn.twisted.websocket.WebSocketServerProtocol
:members:
:undoc-members:
:show-inheritance:
autobahn.twisted.forwarder
--------------------------
.. automodule:: autobahn.twisted.forwarder
.. autoclass:: autobahn.twisted.websocket.WebSocketClientProtocol
:members:
:undoc-members:
:show-inheritance:
autobahn.twisted.rawsocket
--------------------------
.. automodule:: autobahn.twisted.rawsocket
.. autoclass:: autobahn.twisted.websocket.WebSocketServerFactory
:members:
:undoc-members:
:show-inheritance:
autobahn.twisted.resource
-------------------------
.. automodule:: autobahn.twisted.resource
.. autoclass:: autobahn.twisted.websocket.WebSocketClientFactory
:members:
:undoc-members:
:show-inheritance:
autobahn.twisted.util
---------------------
.. automodule:: autobahn.twisted.util
:members:
:undoc-members:
:show-inheritance:
autobahn.twisted.wamp
---------------------
.. automodule:: autobahn.twisted.wamp
:members:
:undoc-members:
:show-inheritance:
autobahn.twisted.websocket
--------------------------
.. automodule:: autobahn.twisted.websocket
:members:
:undoc-members:
:show-inheritance:
Module contents
---------------
.. automodule:: autobahn.twisted
:members:
:undoc-members:
:show-inheritance:

6
docs/reference/autobahn.util.rst Normal file
View File

@ -0,0 +1,6 @@
Module ``autobahn.util``
========================
.. automodule:: autobahn.util
:members:

107
docs/reference/autobahn.wamp.rst
View File

@ -1,95 +1,36 @@
autobahn.wamp
=============
Module ``autobahn.wamp``
========================
Submodules
WAMP Interfaces
---------------
.. automodule:: autobahn.wamp.interfaces
:members:
WAMP Types
----------
autobahn.wamp.auth
------------------
.. automodule:: autobahn.wamp.types
:members:
WAMP Exceptions
---------------
.. automodule:: autobahn.wamp.exception
:members:
WAMP Authentication and Encryption
----------------------------------
.. automodule:: autobahn.wamp.auth
:members:
:show-inheritance:
autobahn.wamp.exception
-----------------------
.. automodule:: autobahn.wamp.exception
:members:
:show-inheritance:
autobahn.wamp.interfaces
------------------------
.. automodule:: autobahn.wamp.interfaces
:members:
:show-inheritance:
autobahn.wamp.message
---------------------
.. automodule:: autobahn.wamp.message
:members:
:show-inheritance:
autobahn.wamp.protocol
----------------------
.. automodule:: autobahn.wamp.protocol
:members:
:show-inheritance:
autobahn.wamp.role
------------------
.. automodule:: autobahn.wamp.role
:members:
:show-inheritance:
autobahn.wamp.serializer
------------------------
.. automodule:: autobahn.wamp.serializer
:members:
:show-inheritance:
autobahn.wamp.types
-------------------
These are plain value-holding classes used in the public WAMP API of Autobahn.
.. automodule:: autobahn.wamp.types
:members:
autobahn.wamp.cryptobox
-----------------------
.. automodule:: autobahn.wamp.cryptobox
:members:
autobahn.wamp.cryptosign
------------------------
.. automodule:: autobahn.wamp.cryptosign
:members:
autobahn.wamp.uri
-----------------
.. automodule:: autobahn.wamp.uri
.. automodule:: autobahn.wamp.cryptobox
:members:
:show-inheritance:
autobahn.wamp.websocket
-----------------------
.. automodule:: autobahn.wamp.websocket
:members:
:show-inheritance:
Module contents
---------------
.. automodule:: autobahn.wamp
:members:
:show-inheritance:

36
docs/reference/autobahn.websocket.rst
View File

@ -1,23 +1,35 @@
autobahn.websocket
==================
Module ``autobahn.websocket``
=============================
WebSocket Channel Interface
---------------------------
WebSocket Interfaces
--------------------
.. autoclass:: autobahn.websocket.IWebSocketChannel
.. autoclass:: autobahn.websocket.interfaces.IWebSocketChannel
:members:
.. autoclass:: autobahn.websocket.interfaces.IWebSocketServerChannelFactory
:members:
.. autoclass:: autobahn.websocket.interfaces.IWebSocketClientChannelFactory
:members:
WebSocket Messages
------------------
WebSocket Types
---------------
.. autoclass:: autobahn.websocket.Message
.. automodule:: autobahn.websocket.types
:members:
.. autoclass:: autobahn.websocket.IncomingMessage
:show-inheritance:
WebSocket Compression
---------------------
.. automodule:: autobahn.websocket.compress
:members:
.. autoclass:: autobahn.websocket.OutgoingMessage
:show-inheritance:
WebSocket Utils
---------------
.. automodule:: autobahn.websocket.util
:members: