`_
.. raw:: html
websockets for enterprise
Available as part of the Tidelift Subscription
The maintainers of websockets and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. Learn more.
(If you contribute to websockets and would like to become an official support provider, let me know.)
Why should I use ``websockets``?
--------------------------------
The development of ``websockets`` is shaped by four principles:
1. **Simplicity**: all you need to understand is ``msg = await ws.recv()`` and
``await ws.send(msg)``; ``websockets`` takes care of managing connections
so you can focus on your application.
2. **Robustness**: ``websockets`` is built for production; for example it was
the only library to `handle backpressure correctly`_ before the issue
became widely known in the Python community.
3. **Quality**: ``websockets`` is heavily tested. Continuous integration fails
under 100% branch coverage. Also it passes the industry-standard `Autobahn
Testsuite`_.
4. **Performance**: memory use is configurable. An extension written in C
accelerates expensive operations. It's pre-compiled for Linux, macOS and
Windows and packaged in the wheel format for each system and Python version.
Documentation is a first class concern in the project. Head over to `Read the
Docs`_ and see for yourself.
.. _Read the Docs: https://websockets.readthedocs.io/
.. _handle backpressure correctly: https://vorpus.org/blog/some-thoughts-on-asynchronous-api-design-in-a-post-asyncawait-world/#websocket-servers
.. _Autobahn Testsuite: https://github.com/aaugustin/websockets/blob/master/compliance/README.rst
Why shouldn't I use ``websockets``?
-----------------------------------
* If you prefer callbacks over coroutines: ``websockets`` was created to
provide the best coroutine-based API to manage WebSocket connections in
Python. Pick another library for a callback-based API.
* If you're looking for a mixed HTTP / WebSocket library: ``websockets`` aims
at being an excellent implementation of :rfc:`6455`: The WebSocket Protocol
and :rfc:`7692`: Compression Extensions for WebSocket. Its support for HTTP
is minimal — just enough for a HTTP health check.
* If you want to use Python 2: ``websockets`` builds upon ``asyncio`` which
only works on Python 3. ``websockets`` requires Python ≥ 3.6.1.
What else?
----------
Bug reports, patches and suggestions are welcome!
To report a security vulnerability, please use the `Tidelift security
contact`_. Tidelift will coordinate the fix and disclosure.
.. _Tidelift security contact: https://tidelift.com/security
For anything else, please open an issue_ or send a `pull request`_.
.. _issue: https://github.com/aaugustin/websockets/issues/new
.. _pull request: https://github.com/aaugustin/websockets/compare/
Participants must uphold the `Contributor Covenant code of conduct`_.
.. _Contributor Covenant code of conduct: https://github.com/aaugustin/websockets/blob/master/CODE_OF_CONDUCT.md
``websockets`` is released under the `BSD license`_.
.. _BSD license: https://github.com/aaugustin/websockets/blob/master/LICENSE
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 011452 x ustar 00 0000000 0000000 28 mtime=1572615610.4777734
websockets-8.1/setup.cfg 0000644 0000765 0000024 00000001011 00000000000 015271 0 ustar 00myk staff 0000000 0000000 [bdist_wheel]
python-tag = py36.py37
[metadata]
license_file = LICENSE
[flake8]
ignore = E731,F403,F405,W503
max-line-length = 88
[isort]
combine_as_imports = True
force_grid_wrap = 0
include_trailing_comma = True
known_standard_library = asyncio
line_length = 88
lines_after_imports = 2
multi_line_output = 3
[coverage:run]
branch = True
omit = */__main__.py
source =
websockets
tests
[coverage:paths]
source =
src/websockets
.tox/*/lib/python*/site-packages/websockets
[egg_info]
tag_build =
tag_date = 0
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 011453 x ustar 00 0000000 0000000 22 mtime=1570344432.0
websockets-8.1/setup.py 0000644 0000765 0000024 00000003517 00000000000 015177 0 ustar 00myk staff 0000000 0000000 import pathlib
import re
import sys
import setuptools
root_dir = pathlib.Path(__file__).parent
description = "An implementation of the WebSocket Protocol (RFC 6455 & 7692)"
long_description = (root_dir / 'README.rst').read_text(encoding='utf-8')
# PyPI disables the "raw" directive.
long_description = re.sub(
r"^\.\. raw:: html.*?^(?=\w)",
"",
long_description,
flags=re.DOTALL | re.MULTILINE,
)
exec((root_dir / 'src' / 'websockets' / 'version.py').read_text(encoding='utf-8'))
if sys.version_info[:3] < (3, 6, 1):
raise Exception("websockets requires Python >= 3.6.1.")
packages = ['websockets', 'websockets/extensions']
ext_modules = [
setuptools.Extension(
'websockets.speedups',
sources=['src/websockets/speedups.c'],
optional=not (root_dir / '.cibuildwheel').exists(),
)
]
setuptools.setup(
name='websockets',
version=version,
description=description,
long_description=long_description,
url='https://github.com/aaugustin/websockets',
author='Aymeric Augustin',
author_email='aymeric.augustin@m4x.org',
license='BSD',
classifiers=[
'Development Status :: 5 - Production/Stable',
'Environment :: Web Environment',
'Intended Audience :: Developers',
'License :: OSI Approved :: BSD License',
'Operating System :: OS Independent',
'Programming Language :: Python',
'Programming Language :: Python :: 3',
'Programming Language :: Python :: 3.6',
'Programming Language :: Python :: 3.7',
'Programming Language :: Python :: 3.8',
],
package_dir = {'': 'src'},
package_data = {'websockets': ['py.typed']},
packages=packages,
ext_modules=ext_modules,
include_package_data=True,
zip_safe=False,
python_requires='>=3.6.1',
test_loader='unittest:TestLoader',
)
././@PaxHeader 0000000 0000000 0000000 00000000033 00000000000 011451 x ustar 00 0000000 0000000 27 mtime=1572615610.465479
websockets-8.1/src/ 0000755 0000765 0000024 00000000000 00000000000 014246 5 ustar 00myk staff 0000000 0000000 ././@PaxHeader 0000000 0000000 0000000 00000000033 00000000000 011451 x ustar 00 0000000 0000000 27 mtime=1572615610.473283
websockets-8.1/src/websockets/ 0000755 0000765 0000024 00000000000 00000000000 016417 5 ustar 00myk staff 0000000 0000000 ././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 011453 x ustar 00 0000000 0000000 22 mtime=1571084701.0
websockets-8.1/src/websockets/__init__.py 0000644 0000765 0000024 00000002442 00000000000 020532 0 ustar 00myk staff 0000000 0000000 # This relies on each of the submodules having an __all__ variable.
from .auth import * # noqa
from .client import * # noqa
from .exceptions import * # noqa
from .protocol import * # noqa
from .server import * # noqa
from .typing import * # noqa
from .uri import * # noqa
from .version import version as __version__ # noqa
__all__ = [
"AbortHandshake",
"basic_auth_protocol_factory",
"BasicAuthWebSocketServerProtocol",
"connect",
"ConnectionClosed",
"ConnectionClosedError",
"ConnectionClosedOK",
"Data",
"DuplicateParameter",
"ExtensionHeader",
"ExtensionParameter",
"InvalidHandshake",
"InvalidHeader",
"InvalidHeaderFormat",
"InvalidHeaderValue",
"InvalidMessage",
"InvalidOrigin",
"InvalidParameterName",
"InvalidParameterValue",
"InvalidState",
"InvalidStatusCode",
"InvalidUpgrade",
"InvalidURI",
"NegotiationError",
"Origin",
"parse_uri",
"PayloadTooBig",
"ProtocolError",
"RedirectHandshake",
"SecurityError",
"serve",
"Subprotocol",
"unix_connect",
"unix_serve",
"WebSocketClientProtocol",
"WebSocketCommonProtocol",
"WebSocketException",
"WebSocketProtocolError",
"WebSocketServer",
"WebSocketServerProtocol",
"WebSocketURI",
]
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 011453 x ustar 00 0000000 0000000 22 mtime=1570344432.0
websockets-8.1/src/websockets/__main__.py 0000644 0000765 0000024 00000014424 00000000000 020516 0 ustar 00myk staff 0000000 0000000 import argparse
import asyncio
import os
import signal
import sys
import threading
from typing import Any, Set
from .client import connect
from .exceptions import ConnectionClosed, format_close
if sys.platform == "win32":
def win_enable_vt100() -> None:
"""
Enable VT-100 for console output on Windows.
See also https://bugs.python.org/issue29059.
"""
import ctypes
STD_OUTPUT_HANDLE = ctypes.c_uint(-11)
INVALID_HANDLE_VALUE = ctypes.c_uint(-1)
ENABLE_VIRTUAL_TERMINAL_PROCESSING = 0x004
handle = ctypes.windll.kernel32.GetStdHandle(STD_OUTPUT_HANDLE)
if handle == INVALID_HANDLE_VALUE:
raise RuntimeError("unable to obtain stdout handle")
cur_mode = ctypes.c_uint()
if ctypes.windll.kernel32.GetConsoleMode(handle, ctypes.byref(cur_mode)) == 0:
raise RuntimeError("unable to query current console mode")
# ctypes ints lack support for the required bit-OR operation.
# Temporarily convert to Py int, do the OR and convert back.
py_int_mode = int.from_bytes(cur_mode, sys.byteorder)
new_mode = ctypes.c_uint(py_int_mode | ENABLE_VIRTUAL_TERMINAL_PROCESSING)
if ctypes.windll.kernel32.SetConsoleMode(handle, new_mode) == 0:
raise RuntimeError("unable to set console mode")
def exit_from_event_loop_thread(
loop: asyncio.AbstractEventLoop, stop: "asyncio.Future[None]"
) -> None:
loop.stop()
if not stop.done():
# When exiting the thread that runs the event loop, raise
# KeyboardInterrupt in the main thread to exit the program.
try:
ctrl_c = signal.CTRL_C_EVENT # Windows
except AttributeError:
ctrl_c = signal.SIGINT # POSIX
os.kill(os.getpid(), ctrl_c)
def print_during_input(string: str) -> None:
sys.stdout.write(
# Save cursor position
"\N{ESC}7"
# Add a new line
"\N{LINE FEED}"
# Move cursor up
"\N{ESC}[A"
# Insert blank line, scroll last line down
"\N{ESC}[L"
# Print string in the inserted blank line
f"{string}\N{LINE FEED}"
# Restore cursor position
"\N{ESC}8"
# Move cursor down
"\N{ESC}[B"
)
sys.stdout.flush()
def print_over_input(string: str) -> None:
sys.stdout.write(
# Move cursor to beginning of line
"\N{CARRIAGE RETURN}"
# Delete current line
"\N{ESC}[K"
# Print string
f"{string}\N{LINE FEED}"
)
sys.stdout.flush()
async def run_client(
uri: str,
loop: asyncio.AbstractEventLoop,
inputs: "asyncio.Queue[str]",
stop: "asyncio.Future[None]",
) -> None:
try:
websocket = await connect(uri)
except Exception as exc:
print_over_input(f"Failed to connect to {uri}: {exc}.")
exit_from_event_loop_thread(loop, stop)
return
else:
print_during_input(f"Connected to {uri}.")
try:
while True:
incoming: asyncio.Future[Any] = asyncio.ensure_future(websocket.recv())
outgoing: asyncio.Future[Any] = asyncio.ensure_future(inputs.get())
done: Set[asyncio.Future[Any]]
pending: Set[asyncio.Future[Any]]
done, pending = await asyncio.wait(
[incoming, outgoing, stop], return_when=asyncio.FIRST_COMPLETED
)
# Cancel pending tasks to avoid leaking them.
if incoming in pending:
incoming.cancel()
if outgoing in pending:
outgoing.cancel()
if incoming in done:
try:
message = incoming.result()
except ConnectionClosed:
break
else:
if isinstance(message, str):
print_during_input("< " + message)
else:
print_during_input("< (binary) " + message.hex())
if outgoing in done:
message = outgoing.result()
await websocket.send(message)
if stop in done:
break
finally:
await websocket.close()
close_status = format_close(websocket.close_code, websocket.close_reason)
print_over_input(f"Connection closed: {close_status}.")
exit_from_event_loop_thread(loop, stop)
def main() -> None:
# If we're on Windows, enable VT100 terminal support.
if sys.platform == "win32":
try:
win_enable_vt100()
except RuntimeError as exc:
sys.stderr.write(
f"Unable to set terminal to VT100 mode. This is only "
f"supported since Win10 anniversary update. Expect "
f"weird symbols on the terminal.\nError: {exc}\n"
)
sys.stderr.flush()
try:
import readline # noqa
except ImportError: # Windows has no `readline` normally
pass
# Parse command line arguments.
parser = argparse.ArgumentParser(
prog="python -m websockets",
description="Interactive WebSocket client.",
add_help=False,
)
parser.add_argument("uri", metavar="")
args = parser.parse_args()
# Create an event loop that will run in a background thread.
loop = asyncio.new_event_loop()
# Create a queue of user inputs. There's no need to limit its size.
inputs: asyncio.Queue[str] = asyncio.Queue(loop=loop)
# Create a stop condition when receiving SIGINT or SIGTERM.
stop: asyncio.Future[None] = loop.create_future()
# Schedule the task that will manage the connection.
asyncio.ensure_future(run_client(args.uri, loop, inputs, stop), loop=loop)
# Start the event loop in a background thread.
thread = threading.Thread(target=loop.run_forever)
thread.start()
# Read from stdin in the main thread in order to receive signals.
try:
while True:
# Since there's no size limit, put_nowait is identical to put.
message = input("> ")
loop.call_soon_threadsafe(inputs.put_nowait, message)
except (KeyboardInterrupt, EOFError): # ^C, ^D
loop.call_soon_threadsafe(stop.set_result, None)
# Wait for the event loop to terminate.
thread.join()
if __name__ == "__main__":
main()
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 011453 x ustar 00 0000000 0000000 22 mtime=1571084468.0
websockets-8.1/src/websockets/auth.py 0000644 0000765 0000024 00000012446 00000000000 017741 0 ustar 00myk staff 0000000 0000000 """
:mod:`websockets.auth` provides HTTP Basic Authentication according to
:rfc:`7235` and :rfc:`7617`.
"""
import functools
import http
from typing import Any, Awaitable, Callable, Iterable, Optional, Tuple, Type, Union
from .exceptions import InvalidHeader
from .headers import build_www_authenticate_basic, parse_authorization_basic
from .http import Headers
from .server import HTTPResponse, WebSocketServerProtocol
__all__ = ["BasicAuthWebSocketServerProtocol", "basic_auth_protocol_factory"]
Credentials = Tuple[str, str]
def is_credentials(value: Any) -> bool:
try:
username, password = value
except (TypeError, ValueError):
return False
else:
return isinstance(username, str) and isinstance(password, str)
class BasicAuthWebSocketServerProtocol(WebSocketServerProtocol):
"""
WebSocket server protocol that enforces HTTP Basic Auth.
"""
def __init__(
self,
*args: Any,
realm: str,
check_credentials: Callable[[str, str], Awaitable[bool]],
**kwargs: Any,
) -> None:
self.realm = realm
self.check_credentials = check_credentials
super().__init__(*args, **kwargs)
async def process_request(
self, path: str, request_headers: Headers
) -> Optional[HTTPResponse]:
"""
Check HTTP Basic Auth and return a HTTP 401 or 403 response if needed.
If authentication succeeds, the username of the authenticated user is
stored in the ``username`` attribute.
"""
try:
authorization = request_headers["Authorization"]
except KeyError:
return (
http.HTTPStatus.UNAUTHORIZED,
[("WWW-Authenticate", build_www_authenticate_basic(self.realm))],
b"Missing credentials\n",
)
try:
username, password = parse_authorization_basic(authorization)
except InvalidHeader:
return (
http.HTTPStatus.UNAUTHORIZED,
[("WWW-Authenticate", build_www_authenticate_basic(self.realm))],
b"Unsupported credentials\n",
)
if not await self.check_credentials(username, password):
return (
http.HTTPStatus.UNAUTHORIZED,
[("WWW-Authenticate", build_www_authenticate_basic(self.realm))],
b"Invalid credentials\n",
)
self.username = username
return await super().process_request(path, request_headers)
def basic_auth_protocol_factory(
realm: str,
credentials: Optional[Union[Credentials, Iterable[Credentials]]] = None,
check_credentials: Optional[Callable[[str, str], Awaitable[bool]]] = None,
create_protocol: Type[
BasicAuthWebSocketServerProtocol
] = BasicAuthWebSocketServerProtocol,
) -> Callable[[Any], BasicAuthWebSocketServerProtocol]:
"""
Protocol factory that enforces HTTP Basic Auth.
``basic_auth_protocol_factory`` is designed to integrate with
:func:`~websockets.server.serve` like this::
websockets.serve(
...,
create_protocol=websockets.basic_auth_protocol_factory(
realm="my dev server",
credentials=("hello", "iloveyou"),
)
)
``realm`` indicates the scope of protection. It should contain only ASCII
characters because the encoding of non-ASCII characters is undefined.
Refer to section 2.2 of :rfc:`7235` for details.
``credentials`` defines hard coded authorized credentials. It can be a
``(username, password)`` pair or a list of such pairs.
``check_credentials`` defines a coroutine that checks whether credentials
are authorized. This coroutine receives ``username`` and ``password``
arguments and returns a :class:`bool`.
One of ``credentials`` or ``check_credentials`` must be provided but not
both.
By default, ``basic_auth_protocol_factory`` creates a factory for building
:class:`BasicAuthWebSocketServerProtocol` instances. You can override this
with the ``create_protocol`` parameter.
:param realm: scope of protection
:param credentials: hard coded credentials
:param check_credentials: coroutine that verifies credentials
:raises TypeError: if the credentials argument has the wrong type
"""
if (credentials is None) == (check_credentials is None):
raise TypeError("provide either credentials or check_credentials")
if credentials is not None:
if is_credentials(credentials):
async def check_credentials(username: str, password: str) -> bool:
return (username, password) == credentials
elif isinstance(credentials, Iterable):
credentials_list = list(credentials)
if all(is_credentials(item) for item in credentials_list):
credentials_dict = dict(credentials_list)
async def check_credentials(username: str, password: str) -> bool:
return credentials_dict.get(username) == password
else:
raise TypeError(f"invalid credentials argument: {credentials}")
else:
raise TypeError(f"invalid credentials argument: {credentials}")
return functools.partial(
create_protocol, realm=realm, check_credentials=check_credentials
)
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 011453 x ustar 00 0000000 0000000 22 mtime=1572595517.0
websockets-8.1/src/websockets/client.py 0000644 0000765 0000024 00000051337 00000000000 020260 0 ustar 00myk staff 0000000 0000000 """
:mod:`websockets.client` defines the WebSocket client APIs.
"""
import asyncio
import collections.abc
import functools
import logging
import warnings
from types import TracebackType
from typing import Any, Generator, List, Optional, Sequence, Tuple, Type, cast
from .exceptions import (
InvalidHandshake,
InvalidHeader,
InvalidMessage,
InvalidStatusCode,
NegotiationError,
RedirectHandshake,
SecurityError,
)
from .extensions.base import ClientExtensionFactory, Extension
from .extensions.permessage_deflate import ClientPerMessageDeflateFactory
from .handshake import build_request, check_response
from .headers import (
build_authorization_basic,
build_extension,
build_subprotocol,
parse_extension,
parse_subprotocol,
)
from .http import USER_AGENT, Headers, HeadersLike, read_response
from .protocol import WebSocketCommonProtocol
from .typing import ExtensionHeader, Origin, Subprotocol
from .uri import WebSocketURI, parse_uri
__all__ = ["connect", "unix_connect", "WebSocketClientProtocol"]
logger = logging.getLogger(__name__)
class WebSocketClientProtocol(WebSocketCommonProtocol):
"""
:class:`~asyncio.Protocol` subclass implementing a WebSocket client.
This class inherits most of its methods from
:class:`~websockets.protocol.WebSocketCommonProtocol`.
"""
is_client = True
side = "client"
def __init__(
self,
*,
origin: Optional[Origin] = None,
extensions: Optional[Sequence[ClientExtensionFactory]] = None,
subprotocols: Optional[Sequence[Subprotocol]] = None,
extra_headers: Optional[HeadersLike] = None,
**kwargs: Any,
) -> None:
self.origin = origin
self.available_extensions = extensions
self.available_subprotocols = subprotocols
self.extra_headers = extra_headers
super().__init__(**kwargs)
def write_http_request(self, path: str, headers: Headers) -> None:
"""
Write request line and headers to the HTTP request.
"""
self.path = path
self.request_headers = headers
logger.debug("%s > GET %s HTTP/1.1", self.side, path)
logger.debug("%s > %r", self.side, headers)
# Since the path and headers only contain ASCII characters,
# we can keep this simple.
request = f"GET {path} HTTP/1.1\r\n"
request += str(headers)
self.transport.write(request.encode())
async def read_http_response(self) -> Tuple[int, Headers]:
"""
Read status line and headers from the HTTP response.
If the response contains a body, it may be read from ``self.reader``
after this coroutine returns.
:raises ~websockets.exceptions.InvalidMessage: if the HTTP message is
malformed or isn't an HTTP/1.1 GET response
"""
try:
status_code, reason, headers = await read_response(self.reader)
except Exception as exc:
raise InvalidMessage("did not receive a valid HTTP response") from exc
logger.debug("%s < HTTP/1.1 %d %s", self.side, status_code, reason)
logger.debug("%s < %r", self.side, headers)
self.response_headers = headers
return status_code, self.response_headers
@staticmethod
def process_extensions(
headers: Headers,
available_extensions: Optional[Sequence[ClientExtensionFactory]],
) -> List[Extension]:
"""
Handle the Sec-WebSocket-Extensions HTTP response header.
Check that each extension is supported, as well as its parameters.
Return the list of accepted extensions.
Raise :exc:`~websockets.exceptions.InvalidHandshake` to abort the
connection.
:rfc:`6455` leaves the rules up to the specification of each
:extension.
To provide this level of flexibility, for each extension accepted by
the server, we check for a match with each extension available in the
client configuration. If no match is found, an exception is raised.
If several variants of the same extension are accepted by the server,
it may be configured severel times, which won't make sense in general.
Extensions must implement their own requirements. For this purpose,
the list of previously accepted extensions is provided.
Other requirements, for example related to mandatory extensions or the
order of extensions, may be implemented by overriding this method.
"""
accepted_extensions: List[Extension] = []
header_values = headers.get_all("Sec-WebSocket-Extensions")
if header_values:
if available_extensions is None:
raise InvalidHandshake("no extensions supported")
parsed_header_values: List[ExtensionHeader] = sum(
[parse_extension(header_value) for header_value in header_values], []
)
for name, response_params in parsed_header_values:
for extension_factory in available_extensions:
# Skip non-matching extensions based on their name.
if extension_factory.name != name:
continue
# Skip non-matching extensions based on their params.
try:
extension = extension_factory.process_response_params(
response_params, accepted_extensions
)
except NegotiationError:
continue
# Add matching extension to the final list.
accepted_extensions.append(extension)
# Break out of the loop once we have a match.
break
# If we didn't break from the loop, no extension in our list
# matched what the server sent. Fail the connection.
else:
raise NegotiationError(
f"Unsupported extension: "
f"name = {name}, params = {response_params}"
)
return accepted_extensions
@staticmethod
def process_subprotocol(
headers: Headers, available_subprotocols: Optional[Sequence[Subprotocol]]
) -> Optional[Subprotocol]:
"""
Handle the Sec-WebSocket-Protocol HTTP response header.
Check that it contains exactly one supported subprotocol.
Return the selected subprotocol.
"""
subprotocol: Optional[Subprotocol] = None
header_values = headers.get_all("Sec-WebSocket-Protocol")
if header_values:
if available_subprotocols is None:
raise InvalidHandshake("no subprotocols supported")
parsed_header_values: Sequence[Subprotocol] = sum(
[parse_subprotocol(header_value) for header_value in header_values], []
)
if len(parsed_header_values) > 1:
subprotocols = ", ".join(parsed_header_values)
raise InvalidHandshake(f"multiple subprotocols: {subprotocols}")
subprotocol = parsed_header_values[0]
if subprotocol not in available_subprotocols:
raise NegotiationError(f"unsupported subprotocol: {subprotocol}")
return subprotocol
async def handshake(
self,
wsuri: WebSocketURI,
origin: Optional[Origin] = None,
available_extensions: Optional[Sequence[ClientExtensionFactory]] = None,
available_subprotocols: Optional[Sequence[Subprotocol]] = None,
extra_headers: Optional[HeadersLike] = None,
) -> None:
"""
Perform the client side of the opening handshake.
:param origin: sets the Origin HTTP header
:param available_extensions: list of supported extensions in the order
in which they should be used
:param available_subprotocols: list of supported subprotocols in order
of decreasing preference
:param extra_headers: sets additional HTTP request headers; it must be
a :class:`~websockets.http.Headers` instance, a
:class:`~collections.abc.Mapping`, or an iterable of ``(name,
value)`` pairs
:raises ~websockets.exceptions.InvalidHandshake: if the handshake
fails
"""
request_headers = Headers()
if wsuri.port == (443 if wsuri.secure else 80): # pragma: no cover
request_headers["Host"] = wsuri.host
else:
request_headers["Host"] = f"{wsuri.host}:{wsuri.port}"
if wsuri.user_info:
request_headers["Authorization"] = build_authorization_basic(
*wsuri.user_info
)
if origin is not None:
request_headers["Origin"] = origin
key = build_request(request_headers)
if available_extensions is not None:
extensions_header = build_extension(
[
(extension_factory.name, extension_factory.get_request_params())
for extension_factory in available_extensions
]
)
request_headers["Sec-WebSocket-Extensions"] = extensions_header
if available_subprotocols is not None:
protocol_header = build_subprotocol(available_subprotocols)
request_headers["Sec-WebSocket-Protocol"] = protocol_header
if extra_headers is not None:
if isinstance(extra_headers, Headers):
extra_headers = extra_headers.raw_items()
elif isinstance(extra_headers, collections.abc.Mapping):
extra_headers = extra_headers.items()
for name, value in extra_headers:
request_headers[name] = value
request_headers.setdefault("User-Agent", USER_AGENT)
self.write_http_request(wsuri.resource_name, request_headers)
status_code, response_headers = await self.read_http_response()
if status_code in (301, 302, 303, 307, 308):
if "Location" not in response_headers:
raise InvalidHeader("Location")
raise RedirectHandshake(response_headers["Location"])
elif status_code != 101:
raise InvalidStatusCode(status_code)
check_response(response_headers, key)
self.extensions = self.process_extensions(
response_headers, available_extensions
)
self.subprotocol = self.process_subprotocol(
response_headers, available_subprotocols
)
self.connection_open()
class Connect:
"""
Connect to the WebSocket server at the given ``uri``.
Awaiting :func:`connect` yields a :class:`WebSocketClientProtocol` which
can then be used to send and receive messages.
:func:`connect` can also be used as a asynchronous context manager. In
that case, the connection is closed when exiting the context.
:func:`connect` is a wrapper around the event loop's
:meth:`~asyncio.loop.create_connection` method. Unknown keyword arguments
are passed to :meth:`~asyncio.loop.create_connection`.
For example, you can set the ``ssl`` keyword argument to a
:class:`~ssl.SSLContext` to enforce some TLS settings. When connecting to
a ``wss://`` URI, if this argument isn't provided explicitly,
:func:`ssl.create_default_context` is called to create a context.
You can connect to a different host and port from those found in ``uri``
by setting ``host`` and ``port`` keyword arguments. This only changes the
destination of the TCP connection. The host name from ``uri`` is still
used in the TLS handshake for secure connections and in the ``Host`` HTTP
header.
The ``create_protocol`` parameter allows customizing the
:class:`~asyncio.Protocol` that manages the connection. It should be a
callable or class accepting the same arguments as
:class:`WebSocketClientProtocol` and returning an instance of
:class:`WebSocketClientProtocol` or a subclass. It defaults to
:class:`WebSocketClientProtocol`.
The behavior of ``ping_interval``, ``ping_timeout``, ``close_timeout``,
``max_size``, ``max_queue``, ``read_limit``, and ``write_limit`` is
described in :class:`~websockets.protocol.WebSocketCommonProtocol`.
:func:`connect` also accepts the following optional arguments:
* ``compression`` is a shortcut to configure compression extensions;
by default it enables the "permessage-deflate" extension; set it to
``None`` to disable compression
* ``origin`` sets the Origin HTTP header
* ``extensions`` is a list of supported extensions in order of
decreasing preference
* ``subprotocols`` is a list of supported subprotocols in order of
decreasing preference
* ``extra_headers`` sets additional HTTP request headers; it can be a
:class:`~websockets.http.Headers` instance, a
:class:`~collections.abc.Mapping`, or an iterable of ``(name, value)``
pairs
:raises ~websockets.uri.InvalidURI: if ``uri`` is invalid
:raises ~websockets.handshake.InvalidHandshake: if the opening handshake
fails
"""
MAX_REDIRECTS_ALLOWED = 10
def __init__(
self,
uri: str,
*,
path: Optional[str] = None,
create_protocol: Optional[Type[WebSocketClientProtocol]] = None,
ping_interval: float = 20,
ping_timeout: float = 20,
close_timeout: Optional[float] = None,
max_size: int = 2 ** 20,
max_queue: int = 2 ** 5,
read_limit: int = 2 ** 16,
write_limit: int = 2 ** 16,
loop: Optional[asyncio.AbstractEventLoop] = None,
legacy_recv: bool = False,
klass: Optional[Type[WebSocketClientProtocol]] = None,
timeout: Optional[float] = None,
compression: Optional[str] = "deflate",
origin: Optional[Origin] = None,
extensions: Optional[Sequence[ClientExtensionFactory]] = None,
subprotocols: Optional[Sequence[Subprotocol]] = None,
extra_headers: Optional[HeadersLike] = None,
**kwargs: Any,
) -> None:
# Backwards compatibility: close_timeout used to be called timeout.
if timeout is None:
timeout = 10
else:
warnings.warn("rename timeout to close_timeout", DeprecationWarning)
# If both are specified, timeout is ignored.
if close_timeout is None:
close_timeout = timeout
# Backwards compatibility: create_protocol used to be called klass.
if klass is None:
klass = WebSocketClientProtocol
else:
warnings.warn("rename klass to create_protocol", DeprecationWarning)
# If both are specified, klass is ignored.
if create_protocol is None:
create_protocol = klass
if loop is None:
loop = asyncio.get_event_loop()
wsuri = parse_uri(uri)
if wsuri.secure:
kwargs.setdefault("ssl", True)
elif kwargs.get("ssl") is not None:
raise ValueError(
"connect() received a ssl argument for a ws:// URI, "
"use a wss:// URI to enable TLS"
)
if compression == "deflate":
if extensions is None:
extensions = []
if not any(
extension_factory.name == ClientPerMessageDeflateFactory.name
for extension_factory in extensions
):
extensions = list(extensions) + [
ClientPerMessageDeflateFactory(client_max_window_bits=True)
]
elif compression is not None:
raise ValueError(f"unsupported compression: {compression}")
factory = functools.partial(
create_protocol,
ping_interval=ping_interval,
ping_timeout=ping_timeout,
close_timeout=close_timeout,
max_size=max_size,
max_queue=max_queue,
read_limit=read_limit,
write_limit=write_limit,
loop=loop,
host=wsuri.host,
port=wsuri.port,
secure=wsuri.secure,
legacy_recv=legacy_recv,
origin=origin,
extensions=extensions,
subprotocols=subprotocols,
extra_headers=extra_headers,
)
if path is None:
host: Optional[str]
port: Optional[int]
if kwargs.get("sock") is None:
host, port = wsuri.host, wsuri.port
else:
# If sock is given, host and port shouldn't be specified.
host, port = None, None
# If host and port are given, override values from the URI.
host = kwargs.pop("host", host)
port = kwargs.pop("port", port)
create_connection = functools.partial(
loop.create_connection, factory, host, port, **kwargs
)
else:
create_connection = functools.partial(
loop.create_unix_connection, factory, path, **kwargs
)
# This is a coroutine function.
self._create_connection = create_connection
self._wsuri = wsuri
def handle_redirect(self, uri: str) -> None:
# Update the state of this instance to connect to a new URI.
old_wsuri = self._wsuri
new_wsuri = parse_uri(uri)
# Forbid TLS downgrade.
if old_wsuri.secure and not new_wsuri.secure:
raise SecurityError("redirect from WSS to WS")
same_origin = (
old_wsuri.host == new_wsuri.host and old_wsuri.port == new_wsuri.port
)
# Rewrite the host and port arguments for cross-origin redirects.
# This preserves connection overrides with the host and port
# arguments if the redirect points to the same host and port.
if not same_origin:
# Replace the host and port argument passed to the protocol factory.
factory = self._create_connection.args[0]
factory = functools.partial(
factory.func,
*factory.args,
**dict(factory.keywords, host=new_wsuri.host, port=new_wsuri.port),
)
# Replace the host and port argument passed to create_connection.
self._create_connection = functools.partial(
self._create_connection.func,
*(factory, new_wsuri.host, new_wsuri.port),
**self._create_connection.keywords,
)
# Set the new WebSocket URI. This suffices for same-origin redirects.
self._wsuri = new_wsuri
# async with connect(...)
async def __aenter__(self) -> WebSocketClientProtocol:
return await self
async def __aexit__(
self,
exc_type: Optional[Type[BaseException]],
exc_value: Optional[BaseException],
traceback: Optional[TracebackType],
) -> None:
await self.ws_client.close()
# await connect(...)
def __await__(self) -> Generator[Any, None, WebSocketClientProtocol]:
# Create a suitable iterator by calling __await__ on a coroutine.
return self.__await_impl__().__await__()
async def __await_impl__(self) -> WebSocketClientProtocol:
for redirects in range(self.MAX_REDIRECTS_ALLOWED):
transport, protocol = await self._create_connection()
# https://github.com/python/typeshed/pull/2756
transport = cast(asyncio.Transport, transport)
protocol = cast(WebSocketClientProtocol, protocol)
try:
try:
await protocol.handshake(
self._wsuri,
origin=protocol.origin,
available_extensions=protocol.available_extensions,
available_subprotocols=protocol.available_subprotocols,
extra_headers=protocol.extra_headers,
)
except Exception:
protocol.fail_connection()
await protocol.wait_closed()
raise
else:
self.ws_client = protocol
return protocol
except RedirectHandshake as exc:
self.handle_redirect(exc.uri)
else:
raise SecurityError("too many redirects")
# yield from connect(...)
__iter__ = __await__
connect = Connect
def unix_connect(path: str, uri: str = "ws://localhost/", **kwargs: Any) -> Connect:
"""
Similar to :func:`connect`, but for connecting to a Unix socket.
This function calls the event loop's
:meth:`~asyncio.loop.create_unix_connection` method.
It is only available on Unix.
It's mainly useful for debugging servers listening on Unix sockets.
:param path: file system path to the Unix socket
:param uri: WebSocket URI
"""
return connect(uri=uri, path=path, **kwargs)
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 011453 x ustar 00 0000000 0000000 22 mtime=1571084468.0
websockets-8.1/src/websockets/exceptions.py 0000644 0000765 0000024 00000021170 00000000000 021153 0 ustar 00myk staff 0000000 0000000 """
:mod:`websockets.exceptions` defines the following exception hierarchy:
* :exc:`WebSocketException`
* :exc:`ConnectionClosed`
* :exc:`ConnectionClosedError`
* :exc:`ConnectionClosedOK`
* :exc:`InvalidHandshake`
* :exc:`SecurityError`
* :exc:`InvalidMessage`
* :exc:`InvalidHeader`
* :exc:`InvalidHeaderFormat`
* :exc:`InvalidHeaderValue`
* :exc:`InvalidOrigin`
* :exc:`InvalidUpgrade`
* :exc:`InvalidStatusCode`
* :exc:`NegotiationError`
* :exc:`DuplicateParameter`
* :exc:`InvalidParameterName`
* :exc:`InvalidParameterValue`
* :exc:`AbortHandshake`
* :exc:`RedirectHandshake`
* :exc:`InvalidState`
* :exc:`InvalidURI`
* :exc:`PayloadTooBig`
* :exc:`ProtocolError`
"""
import http
from typing import Optional
from .http import Headers, HeadersLike
__all__ = [
"WebSocketException",
"ConnectionClosed",
"ConnectionClosedError",
"ConnectionClosedOK",
"InvalidHandshake",
"SecurityError",
"InvalidMessage",
"InvalidHeader",
"InvalidHeaderFormat",
"InvalidHeaderValue",
"InvalidOrigin",
"InvalidUpgrade",
"InvalidStatusCode",
"NegotiationError",
"DuplicateParameter",
"InvalidParameterName",
"InvalidParameterValue",
"AbortHandshake",
"RedirectHandshake",
"InvalidState",
"InvalidURI",
"PayloadTooBig",
"ProtocolError",
"WebSocketProtocolError",
]
class WebSocketException(Exception):
"""
Base class for all exceptions defined by :mod:`websockets`.
"""
CLOSE_CODES = {
1000: "OK",
1001: "going away",
1002: "protocol error",
1003: "unsupported type",
# 1004 is reserved
1005: "no status code [internal]",
1006: "connection closed abnormally [internal]",
1007: "invalid data",
1008: "policy violation",
1009: "message too big",
1010: "extension required",
1011: "unexpected error",
1015: "TLS failure [internal]",
}
def format_close(code: int, reason: str) -> str:
"""
Display a human-readable version of the close code and reason.
"""
if 3000 <= code < 4000:
explanation = "registered"
elif 4000 <= code < 5000:
explanation = "private use"
else:
explanation = CLOSE_CODES.get(code, "unknown")
result = f"code = {code} ({explanation}), "
if reason:
result += f"reason = {reason}"
else:
result += "no reason"
return result
class ConnectionClosed(WebSocketException):
"""
Raised when trying to interact with a closed connection.
Provides the connection close code and reason in its ``code`` and
``reason`` attributes respectively.
"""
def __init__(self, code: int, reason: str) -> None:
self.code = code
self.reason = reason
super().__init__(format_close(code, reason))
class ConnectionClosedError(ConnectionClosed):
"""
Like :exc:`ConnectionClosed`, when the connection terminated with an error.
This means the close code is different from 1000 (OK) and 1001 (going away).
"""
def __init__(self, code: int, reason: str) -> None:
assert code != 1000 and code != 1001
super().__init__(code, reason)
class ConnectionClosedOK(ConnectionClosed):
"""
Like :exc:`ConnectionClosed`, when the connection terminated properly.
This means the close code is 1000 (OK) or 1001 (going away).
"""
def __init__(self, code: int, reason: str) -> None:
assert code == 1000 or code == 1001
super().__init__(code, reason)
class InvalidHandshake(WebSocketException):
"""
Raised during the handshake when the WebSocket connection fails.
"""
class SecurityError(InvalidHandshake):
"""
Raised when a handshake request or response breaks a security rule.
Security limits are hard coded.
"""
class InvalidMessage(InvalidHandshake):
"""
Raised when a handshake request or response is malformed.
"""
class InvalidHeader(InvalidHandshake):
"""
Raised when a HTTP header doesn't have a valid format or value.
"""
def __init__(self, name: str, value: Optional[str] = None) -> None:
self.name = name
self.value = value
if value is None:
message = f"missing {name} header"
elif value == "":
message = f"empty {name} header"
else:
message = f"invalid {name} header: {value}"
super().__init__(message)
class InvalidHeaderFormat(InvalidHeader):
"""
Raised when a HTTP header cannot be parsed.
The format of the header doesn't match the grammar for that header.
"""
def __init__(self, name: str, error: str, header: str, pos: int) -> None:
self.name = name
error = f"{error} at {pos} in {header}"
super().__init__(name, error)
class InvalidHeaderValue(InvalidHeader):
"""
Raised when a HTTP header has a wrong value.
The format of the header is correct but a value isn't acceptable.
"""
class InvalidOrigin(InvalidHeader):
"""
Raised when the Origin header in a request isn't allowed.
"""
def __init__(self, origin: Optional[str]) -> None:
super().__init__("Origin", origin)
class InvalidUpgrade(InvalidHeader):
"""
Raised when the Upgrade or Connection header isn't correct.
"""
class InvalidStatusCode(InvalidHandshake):
"""
Raised when a handshake response status code is invalid.
The integer status code is available in the ``status_code`` attribute.
"""
def __init__(self, status_code: int) -> None:
self.status_code = status_code
message = f"server rejected WebSocket connection: HTTP {status_code}"
super().__init__(message)
class NegotiationError(InvalidHandshake):
"""
Raised when negotiating an extension fails.
"""
class DuplicateParameter(NegotiationError):
"""
Raised when a parameter name is repeated in an extension header.
"""
def __init__(self, name: str) -> None:
self.name = name
message = f"duplicate parameter: {name}"
super().__init__(message)
class InvalidParameterName(NegotiationError):
"""
Raised when a parameter name in an extension header is invalid.
"""
def __init__(self, name: str) -> None:
self.name = name
message = f"invalid parameter name: {name}"
super().__init__(message)
class InvalidParameterValue(NegotiationError):
"""
Raised when a parameter value in an extension header is invalid.
"""
def __init__(self, name: str, value: Optional[str]) -> None:
self.name = name
self.value = value
if value is None:
message = f"missing value for parameter {name}"
elif value == "":
message = f"empty value for parameter {name}"
else:
message = f"invalid value for parameter {name}: {value}"
super().__init__(message)
class AbortHandshake(InvalidHandshake):
"""
Raised to abort the handshake on purpose and return a HTTP response.
This exception is an implementation detail.
The public API is :meth:`~server.WebSocketServerProtocol.process_request`.
"""
def __init__(
self, status: http.HTTPStatus, headers: HeadersLike, body: bytes = b""
) -> None:
self.status = status
self.headers = Headers(headers)
self.body = body
message = f"HTTP {status}, {len(self.headers)} headers, {len(body)} bytes"
super().__init__(message)
class RedirectHandshake(InvalidHandshake):
"""
Raised when a handshake gets redirected.
This exception is an implementation detail.
"""
def __init__(self, uri: str) -> None:
self.uri = uri
def __str__(self) -> str:
return f"redirect to {self.uri}"
class InvalidState(WebSocketException, AssertionError):
"""
Raised when an operation is forbidden in the current state.
This exception is an implementation detail.
It should never be raised in normal circumstances.
"""
class InvalidURI(WebSocketException):
"""
Raised when connecting to an URI that isn't a valid WebSocket URI.
"""
def __init__(self, uri: str) -> None:
self.uri = uri
message = "{} isn't a valid URI".format(uri)
super().__init__(message)
class PayloadTooBig(WebSocketException):
"""
Raised when receiving a frame with a payload exceeding the maximum size.
"""
class ProtocolError(WebSocketException):
"""
Raised when the other side breaks the protocol.
"""
WebSocketProtocolError = ProtocolError # for backwards compatibility
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 011452 x ustar 00 0000000 0000000 28 mtime=1572615610.4764388
websockets-8.1/src/websockets/extensions/ 0000755 0000765 0000024 00000000000 00000000000 020616 5 ustar 00myk staff 0000000 0000000 ././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 011453 x ustar 00 0000000 0000000 22 mtime=1546111875.0
websockets-8.1/src/websockets/extensions/__init__.py 0000644 0000765 0000024 00000000000 00000000000 022715 0 ustar 00myk staff 0000000 0000000 ././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 011453 x ustar 00 0000000 0000000 22 mtime=1571084468.0
websockets-8.1/src/websockets/extensions/base.py 0000644 0000765 0000024 00000005340 00000000000 022104 0 ustar 00myk staff 0000000 0000000 """
:mod:`websockets.extensions.base` defines abstract classes for implementing
extensions.
See `section 9 of RFC 6455`_.
.. _section 9 of RFC 6455: http://tools.ietf.org/html/rfc6455#section-9
"""
from typing import List, Optional, Sequence, Tuple
from ..framing import Frame
from ..typing import ExtensionName, ExtensionParameter
__all__ = ["Extension", "ClientExtensionFactory", "ServerExtensionFactory"]
class Extension:
"""
Abstract class for extensions.
"""
@property
def name(self) -> ExtensionName:
"""
Extension identifier.
"""
def decode(self, frame: Frame, *, max_size: Optional[int] = None) -> Frame:
"""
Decode an incoming frame.
:param frame: incoming frame
:param max_size: maximum payload size in bytes
"""
def encode(self, frame: Frame) -> Frame:
"""
Encode an outgoing frame.
:param frame: outgoing frame
"""
class ClientExtensionFactory:
"""
Abstract class for client-side extension factories.
"""
@property
def name(self) -> ExtensionName:
"""
Extension identifier.
"""
def get_request_params(self) -> List[ExtensionParameter]:
"""
Build request parameters.
Return a list of ``(name, value)`` pairs.
"""
def process_response_params(
self,
params: Sequence[ExtensionParameter],
accepted_extensions: Sequence[Extension],
) -> Extension:
"""
Process response parameters received from the server.
:param params: list of ``(name, value)`` pairs.
:param accepted_extensions: list of previously accepted extensions.
:raises ~websockets.exceptions.NegotiationError: if parameters aren't
acceptable
"""
class ServerExtensionFactory:
"""
Abstract class for server-side extension factories.
"""
@property
def name(self) -> ExtensionName:
"""
Extension identifier.
"""
def process_request_params(
self,
params: Sequence[ExtensionParameter],
accepted_extensions: Sequence[Extension],
) -> Tuple[List[ExtensionParameter], Extension]:
"""
Process request parameters received from the client.
To accept the offer, return a 2-uple containing:
- response parameters: a list of ``(name, value)`` pairs
- an extension: an instance of a subclass of :class:`Extension`
:param params: list of ``(name, value)`` pairs.
:param accepted_extensions: list of previously accepted extensions.
:raises ~websockets.exceptions.NegotiationError: to reject the offer,
if parameters aren't acceptable
"""
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 011453 x ustar 00 0000000 0000000 22 mtime=1571084468.0
websockets-8.1/src/websockets/extensions/permessage_deflate.py 0000644 0000765 0000024 00000052342 00000000000 025015 0 ustar 00myk staff 0000000 0000000 """
:mod:`websockets.extensions.permessage_deflate` implements the Compression
Extensions for WebSocket as specified in :rfc:`7692`.
"""
import zlib
from typing import Any, Dict, List, Optional, Sequence, Tuple, Union
from ..exceptions import (
DuplicateParameter,
InvalidParameterName,
InvalidParameterValue,
NegotiationError,
PayloadTooBig,
)
from ..framing import CTRL_OPCODES, OP_CONT, Frame
from ..typing import ExtensionName, ExtensionParameter
from .base import ClientExtensionFactory, Extension, ServerExtensionFactory
__all__ = [
"PerMessageDeflate",
"ClientPerMessageDeflateFactory",
"ServerPerMessageDeflateFactory",
]
_EMPTY_UNCOMPRESSED_BLOCK = b"\x00\x00\xff\xff"
_MAX_WINDOW_BITS_VALUES = [str(bits) for bits in range(8, 16)]
class PerMessageDeflate(Extension):
"""
Per-Message Deflate extension.
"""
name = ExtensionName("permessage-deflate")
def __init__(
self,
remote_no_context_takeover: bool,
local_no_context_takeover: bool,
remote_max_window_bits: int,
local_max_window_bits: int,
compress_settings: Optional[Dict[Any, Any]] = None,
) -> None:
"""
Configure the Per-Message Deflate extension.
"""
if compress_settings is None:
compress_settings = {}
assert remote_no_context_takeover in [False, True]
assert local_no_context_takeover in [False, True]
assert 8 <= remote_max_window_bits <= 15
assert 8 <= local_max_window_bits <= 15
assert "wbits" not in compress_settings
self.remote_no_context_takeover = remote_no_context_takeover
self.local_no_context_takeover = local_no_context_takeover
self.remote_max_window_bits = remote_max_window_bits
self.local_max_window_bits = local_max_window_bits
self.compress_settings = compress_settings
if not self.remote_no_context_takeover:
self.decoder = zlib.decompressobj(wbits=-self.remote_max_window_bits)
if not self.local_no_context_takeover:
self.encoder = zlib.compressobj(
wbits=-self.local_max_window_bits, **self.compress_settings
)
# To handle continuation frames properly, we must keep track of
# whether that initial frame was encoded.
self.decode_cont_data = False
# There's no need for self.encode_cont_data because we always encode
# outgoing frames, so it would always be True.
def __repr__(self) -> str:
return (
f"PerMessageDeflate("
f"remote_no_context_takeover={self.remote_no_context_takeover}, "
f"local_no_context_takeover={self.local_no_context_takeover}, "
f"remote_max_window_bits={self.remote_max_window_bits}, "
f"local_max_window_bits={self.local_max_window_bits})"
)
def decode(self, frame: Frame, *, max_size: Optional[int] = None) -> Frame:
"""
Decode an incoming frame.
"""
# Skip control frames.
if frame.opcode in CTRL_OPCODES:
return frame
# Handle continuation data frames:
# - skip if the initial data frame wasn't encoded
# - reset "decode continuation data" flag if it's a final frame
if frame.opcode == OP_CONT:
if not self.decode_cont_data:
return frame
if frame.fin:
self.decode_cont_data = False
# Handle text and binary data frames:
# - skip if the frame isn't encoded
# - set "decode continuation data" flag if it's a non-final frame
else:
if not frame.rsv1:
return frame
if not frame.fin: # frame.rsv1 is True at this point
self.decode_cont_data = True
# Re-initialize per-message decoder.
if self.remote_no_context_takeover:
self.decoder = zlib.decompressobj(wbits=-self.remote_max_window_bits)
# Uncompress compressed frames. Protect against zip bombs by
# preventing zlib from decompressing more than max_length bytes
# (except when the limit is disabled with max_size = None).
data = frame.data
if frame.fin:
data += _EMPTY_UNCOMPRESSED_BLOCK
max_length = 0 if max_size is None else max_size
data = self.decoder.decompress(data, max_length)
if self.decoder.unconsumed_tail:
raise PayloadTooBig(
f"Uncompressed payload length exceeds size limit (? > {max_size} bytes)"
)
# Allow garbage collection of the decoder if it won't be reused.
if frame.fin and self.remote_no_context_takeover:
del self.decoder
return frame._replace(data=data, rsv1=False)
def encode(self, frame: Frame) -> Frame:
"""
Encode an outgoing frame.
"""
# Skip control frames.
if frame.opcode in CTRL_OPCODES:
return frame
# Since we always encode and never fragment messages, there's no logic
# similar to decode() here at this time.
if frame.opcode != OP_CONT:
# Re-initialize per-message decoder.
if self.local_no_context_takeover:
self.encoder = zlib.compressobj(
wbits=-self.local_max_window_bits, **self.compress_settings
)
# Compress data frames.
data = self.encoder.compress(frame.data) + self.encoder.flush(zlib.Z_SYNC_FLUSH)
if frame.fin and data.endswith(_EMPTY_UNCOMPRESSED_BLOCK):
data = data[:-4]
# Allow garbage collection of the encoder if it won't be reused.
if frame.fin and self.local_no_context_takeover:
del self.encoder
return frame._replace(data=data, rsv1=True)
def _build_parameters(
server_no_context_takeover: bool,
client_no_context_takeover: bool,
server_max_window_bits: Optional[int],
client_max_window_bits: Optional[Union[int, bool]],
) -> List[ExtensionParameter]:
"""
Build a list of ``(name, value)`` pairs for some compression parameters.
"""
params: List[ExtensionParameter] = []
if server_no_context_takeover:
params.append(("server_no_context_takeover", None))
if client_no_context_takeover:
params.append(("client_no_context_takeover", None))
if server_max_window_bits:
params.append(("server_max_window_bits", str(server_max_window_bits)))
if client_max_window_bits is True: # only in handshake requests
params.append(("client_max_window_bits", None))
elif client_max_window_bits:
params.append(("client_max_window_bits", str(client_max_window_bits)))
return params
def _extract_parameters(
params: Sequence[ExtensionParameter], *, is_server: bool
) -> Tuple[bool, bool, Optional[int], Optional[Union[int, bool]]]:
"""
Extract compression parameters from a list of ``(name, value)`` pairs.
If ``is_server`` is ``True``, ``client_max_window_bits`` may be provided
without a value. This is only allow in handshake requests.
"""
server_no_context_takeover: bool = False
client_no_context_takeover: bool = False
server_max_window_bits: Optional[int] = None
client_max_window_bits: Optional[Union[int, bool]] = None
for name, value in params:
if name == "server_no_context_takeover":
if server_no_context_takeover:
raise DuplicateParameter(name)
if value is None:
server_no_context_takeover = True
else:
raise InvalidParameterValue(name, value)
elif name == "client_no_context_takeover":
if client_no_context_takeover:
raise DuplicateParameter(name)
if value is None:
client_no_context_takeover = True
else:
raise InvalidParameterValue(name, value)
elif name == "server_max_window_bits":
if server_max_window_bits is not None:
raise DuplicateParameter(name)
if value in _MAX_WINDOW_BITS_VALUES:
server_max_window_bits = int(value)
else:
raise InvalidParameterValue(name, value)
elif name == "client_max_window_bits":
if client_max_window_bits is not None:
raise DuplicateParameter(name)
if is_server and value is None: # only in handshake requests
client_max_window_bits = True
elif value in _MAX_WINDOW_BITS_VALUES:
client_max_window_bits = int(value)
else:
raise InvalidParameterValue(name, value)
else:
raise InvalidParameterName(name)
return (
server_no_context_takeover,
client_no_context_takeover,
server_max_window_bits,
client_max_window_bits,
)
class ClientPerMessageDeflateFactory(ClientExtensionFactory):
"""
Client-side extension factory for the Per-Message Deflate extension.
Parameters behave as described in `section 7.1 of RFC 7692`_. Set them to
``True`` to include them in the negotiation offer without a value or to an
integer value to include them with this value.
.. _section 7.1 of RFC 7692: https://tools.ietf.org/html/rfc7692#section-7.1
:param server_no_context_takeover: defaults to ``False``
:param client_no_context_takeover: defaults to ``False``
:param server_max_window_bits: optional, defaults to ``None``
:param client_max_window_bits: optional, defaults to ``None``
:param compress_settings: optional, keyword arguments for
:func:`zlib.compressobj`, excluding ``wbits``
"""
name = ExtensionName("permessage-deflate")
def __init__(
self,
server_no_context_takeover: bool = False,
client_no_context_takeover: bool = False,
server_max_window_bits: Optional[int] = None,
client_max_window_bits: Optional[Union[int, bool]] = None,
compress_settings: Optional[Dict[str, Any]] = None,
) -> None:
"""
Configure the Per-Message Deflate extension factory.
"""
if not (server_max_window_bits is None or 8 <= server_max_window_bits <= 15):
raise ValueError("server_max_window_bits must be between 8 and 15")
if not (
client_max_window_bits is None
or client_max_window_bits is True
or 8 <= client_max_window_bits <= 15
):
raise ValueError("client_max_window_bits must be between 8 and 15")
if compress_settings is not None and "wbits" in compress_settings:
raise ValueError(
"compress_settings must not include wbits, "
"set client_max_window_bits instead"
)
self.server_no_context_takeover = server_no_context_takeover
self.client_no_context_takeover = client_no_context_takeover
self.server_max_window_bits = server_max_window_bits
self.client_max_window_bits = client_max_window_bits
self.compress_settings = compress_settings
def get_request_params(self) -> List[ExtensionParameter]:
"""
Build request parameters.
"""
return _build_parameters(
self.server_no_context_takeover,
self.client_no_context_takeover,
self.server_max_window_bits,
self.client_max_window_bits,
)
def process_response_params(
self,
params: Sequence[ExtensionParameter],
accepted_extensions: Sequence["Extension"],
) -> PerMessageDeflate:
"""
Process response parameters.
Return an extension instance.
"""
if any(other.name == self.name for other in accepted_extensions):
raise NegotiationError(f"received duplicate {self.name}")
# Request parameters are available in instance variables.
# Load response parameters in local variables.
(
server_no_context_takeover,
client_no_context_takeover,
server_max_window_bits,
client_max_window_bits,
) = _extract_parameters(params, is_server=False)
# After comparing the request and the response, the final
# configuration must be available in the local variables.
# server_no_context_takeover
#
# Req. Resp. Result
# ------ ------ --------------------------------------------------
# False False False
# False True True
# True False Error!
# True True True
if self.server_no_context_takeover:
if not server_no_context_takeover:
raise NegotiationError("expected server_no_context_takeover")
# client_no_context_takeover
#
# Req. Resp. Result
# ------ ------ --------------------------------------------------
# False False False
# False True True
# True False True - must change value
# True True True
if self.client_no_context_takeover:
if not client_no_context_takeover:
client_no_context_takeover = True
# server_max_window_bits
# Req. Resp. Result
# ------ ------ --------------------------------------------------
# None None None
# None 8≤M≤15 M
# 8≤N≤15 None Error!
# 8≤N≤15 8≤M≤N M
# 8≤N≤15 N self.server_max_window_bits:
raise NegotiationError("unsupported server_max_window_bits")
# client_max_window_bits
# Req. Resp. Result
# ------ ------ --------------------------------------------------
# None None None
# None 8≤M≤15 Error!
# True None None
# True 8≤M≤15 M
# 8≤N≤15 None N - must change value
# 8≤N≤15 8≤M≤N M
# 8≤N≤15 N self.client_max_window_bits:
raise NegotiationError("unsupported client_max_window_bits")
return PerMessageDeflate(
server_no_context_takeover, # remote_no_context_takeover
client_no_context_takeover, # local_no_context_takeover
server_max_window_bits or 15, # remote_max_window_bits
client_max_window_bits or 15, # local_max_window_bits
self.compress_settings,
)
class ServerPerMessageDeflateFactory(ServerExtensionFactory):
"""
Server-side extension factory for the Per-Message Deflate extension.
Parameters behave as described in `section 7.1 of RFC 7692`_. Set them to
``True`` to include them in the negotiation offer without a value or to an
integer value to include them with this value.
.. _section 7.1 of RFC 7692: https://tools.ietf.org/html/rfc7692#section-7.1
:param server_no_context_takeover: defaults to ``False``
:param client_no_context_takeover: defaults to ``False``
:param server_max_window_bits: optional, defaults to ``None``
:param client_max_window_bits: optional, defaults to ``None``
:param compress_settings: optional, keyword arguments for
:func:`zlib.compressobj`, excluding ``wbits``
"""
name = ExtensionName("permessage-deflate")
def __init__(
self,
server_no_context_takeover: bool = False,
client_no_context_takeover: bool = False,
server_max_window_bits: Optional[int] = None,
client_max_window_bits: Optional[int] = None,
compress_settings: Optional[Dict[str, Any]] = None,
) -> None:
"""
Configure the Per-Message Deflate extension factory.
"""
if not (server_max_window_bits is None or 8 <= server_max_window_bits <= 15):
raise ValueError("server_max_window_bits must be between 8 and 15")
if not (client_max_window_bits is None or 8 <= client_max_window_bits <= 15):
raise ValueError("client_max_window_bits must be between 8 and 15")
if compress_settings is not None and "wbits" in compress_settings:
raise ValueError(
"compress_settings must not include wbits, "
"set server_max_window_bits instead"
)
self.server_no_context_takeover = server_no_context_takeover
self.client_no_context_takeover = client_no_context_takeover
self.server_max_window_bits = server_max_window_bits
self.client_max_window_bits = client_max_window_bits
self.compress_settings = compress_settings
def process_request_params(
self,
params: Sequence[ExtensionParameter],
accepted_extensions: Sequence["Extension"],
) -> Tuple[List[ExtensionParameter], PerMessageDeflate]:
"""
Process request parameters.
Return response params and an extension instance.
"""
if any(other.name == self.name for other in accepted_extensions):
raise NegotiationError(f"skipped duplicate {self.name}")
# Load request parameters in local variables.
(
server_no_context_takeover,
client_no_context_takeover,
server_max_window_bits,
client_max_window_bits,
) = _extract_parameters(params, is_server=True)
# Configuration parameters are available in instance variables.
# After comparing the request and the configuration, the response must
# be available in the local variables.
# server_no_context_takeover
#
# Config Req. Resp.
# ------ ------ --------------------------------------------------
# False False False
# False True True
# True False True - must change value to True
# True True True
if self.server_no_context_takeover:
if not server_no_context_takeover:
server_no_context_takeover = True
# client_no_context_takeover
#
# Config Req. Resp.
# ------ ------ --------------------------------------------------
# False False False
# False True True (or False)
# True False True - must change value to True
# True True True (or False)
if self.client_no_context_takeover:
if not client_no_context_takeover:
client_no_context_takeover = True
# server_max_window_bits
# Config Req. Resp.
# ------ ------ --------------------------------------------------
# None None None
# None 8≤M≤15 M
# 8≤N≤15 None N - must change value
# 8≤N≤15 8≤M≤N M
# 8≤N≤15 N self.server_max_window_bits:
server_max_window_bits = self.server_max_window_bits
# client_max_window_bits
# Config Req. Resp.
# ------ ------ --------------------------------------------------
# None None None
# None True None - must change value
# None 8≤M≤15 M (or None)
# 8≤N≤15 None Error!
# 8≤N≤15 True N - must change value
# 8≤N≤15 8≤M≤N M (or None)
# 8≤N≤15 N "Frame":
"""
Read a WebSocket frame.
:param reader: coroutine that reads exactly the requested number of
bytes, unless the end of file is reached
:param mask: whether the frame should be masked i.e. whether the read
happens on the server side
:param max_size: maximum payload size in bytes
:param extensions: list of classes with a ``decode()`` method that
transforms the frame and return a new frame; extensions are applied
in reverse order
:raises ~websockets.exceptions.PayloadTooBig: if the frame exceeds
``max_size``
:raises ~websockets.exceptions.ProtocolError: if the frame
contains incorrect values
"""
# Read the header.
data = await reader(2)
head1, head2 = struct.unpack("!BB", data)
# While not Pythonic, this is marginally faster than calling bool().
fin = True if head1 & 0b10000000 else False
rsv1 = True if head1 & 0b01000000 else False
rsv2 = True if head1 & 0b00100000 else False
rsv3 = True if head1 & 0b00010000 else False
opcode = head1 & 0b00001111
if (True if head2 & 0b10000000 else False) != mask:
raise ProtocolError("incorrect masking")
length = head2 & 0b01111111
if length == 126:
data = await reader(2)
(length,) = struct.unpack("!H", data)
elif length == 127:
data = await reader(8)
(length,) = struct.unpack("!Q", data)
if max_size is not None and length > max_size:
raise PayloadTooBig(
f"payload length exceeds size limit ({length} > {max_size} bytes)"
)
if mask:
mask_bits = await reader(4)
# Read the data.
data = await reader(length)
if mask:
data = apply_mask(data, mask_bits)
frame = cls(fin, opcode, data, rsv1, rsv2, rsv3)
if extensions is None:
extensions = []
for extension in reversed(extensions):
frame = extension.decode(frame, max_size=max_size)
frame.check()
return frame
def write(
frame,
write: Callable[[bytes], Any],
*,
mask: bool,
extensions: Optional[Sequence["websockets.extensions.base.Extension"]] = None,
) -> None:
"""
Write a WebSocket frame.
:param frame: frame to write
:param write: function that writes bytes
:param mask: whether the frame should be masked i.e. whether the write
happens on the client side
:param extensions: list of classes with an ``encode()`` method that
transform the frame and return a new frame; extensions are applied
in order
:raises ~websockets.exceptions.ProtocolError: if the frame
contains incorrect values
"""
# The first parameter is called `frame` rather than `self`,
# but it's the instance of class to which this method is bound.
frame.check()
if extensions is None:
extensions = []
for extension in extensions:
frame = extension.encode(frame)
output = io.BytesIO()
# Prepare the header.
head1 = (
(0b10000000 if frame.fin else 0)
| (0b01000000 if frame.rsv1 else 0)
| (0b00100000 if frame.rsv2 else 0)
| (0b00010000 if frame.rsv3 else 0)
| frame.opcode
)
head2 = 0b10000000 if mask else 0
length = len(frame.data)
if length < 126:
output.write(struct.pack("!BB", head1, head2 | length))
elif length < 65536:
output.write(struct.pack("!BBH", head1, head2 | 126, length))
else:
output.write(struct.pack("!BBQ", head1, head2 | 127, length))
if mask:
mask_bits = struct.pack("!I", random.getrandbits(32))
output.write(mask_bits)
# Prepare the data.
if mask:
data = apply_mask(frame.data, mask_bits)
else:
data = frame.data
output.write(data)
# Send the frame.
# The frame is written in a single call to write in order to prevent
# TCP fragmentation. See #68 for details. This also makes it safe to
# send frames concurrently from multiple coroutines.
write(output.getvalue())
def check(frame) -> None:
"""
Check that reserved bits and opcode have acceptable values.
:raises ~websockets.exceptions.ProtocolError: if a reserved
bit or the opcode is invalid
"""
# The first parameter is called `frame` rather than `self`,
# but it's the instance of class to which this method is bound.
if frame.rsv1 or frame.rsv2 or frame.rsv3:
raise ProtocolError("reserved bits must be 0")
if frame.opcode in DATA_OPCODES:
return
elif frame.opcode in CTRL_OPCODES:
if len(frame.data) > 125:
raise ProtocolError("control frame too long")
if not frame.fin:
raise ProtocolError("fragmented control frame")
else:
raise ProtocolError(f"invalid opcode: {frame.opcode}")
def prepare_data(data: Data) -> Tuple[int, bytes]:
"""
Convert a string or byte-like object to an opcode and a bytes-like object.
This function is designed for data frames.
If ``data`` is a :class:`str`, return ``OP_TEXT`` and a :class:`bytes`
object encoding ``data`` in UTF-8.
If ``data`` is a bytes-like object, return ``OP_BINARY`` and a bytes-like
object.
:raises TypeError: if ``data`` doesn't have a supported type
"""
if isinstance(data, str):
return OP_TEXT, data.encode("utf-8")
elif isinstance(data, (bytes, bytearray)):
return OP_BINARY, data
elif isinstance(data, memoryview):
if data.c_contiguous:
return OP_BINARY, data
else:
return OP_BINARY, data.tobytes()
else:
raise TypeError("data must be bytes-like or str")
def encode_data(data: Data) -> bytes:
"""
Convert a string or byte-like object to bytes.
This function is designed for ping and pong frames.
If ``data`` is a :class:`str`, return a :class:`bytes` object encoding
``data`` in UTF-8.
If ``data`` is a bytes-like object, return a :class:`bytes` object.
:raises TypeError: if ``data`` doesn't have a supported type
"""
if isinstance(data, str):
return data.encode("utf-8")
elif isinstance(data, (bytes, bytearray)):
return bytes(data)
elif isinstance(data, memoryview):
return data.tobytes()
else:
raise TypeError("data must be bytes-like or str")
def parse_close(data: bytes) -> Tuple[int, str]:
"""
Parse the payload from a close frame.
Return ``(code, reason)``.
:raises ~websockets.exceptions.ProtocolError: if data is ill-formed
:raises UnicodeDecodeError: if the reason isn't valid UTF-8
"""
length = len(data)
if length >= 2:
(code,) = struct.unpack("!H", data[:2])
check_close(code)
reason = data[2:].decode("utf-8")
return code, reason
elif length == 0:
return 1005, ""
else:
assert length == 1
raise ProtocolError("close frame too short")
def serialize_close(code: int, reason: str) -> bytes:
"""
Serialize the payload for a close frame.
This is the reverse of :func:`parse_close`.
"""
check_close(code)
return struct.pack("!H", code) + reason.encode("utf-8")
def check_close(code: int) -> None:
"""
Check that the close code has an acceptable value for a close frame.
:raises ~websockets.exceptions.ProtocolError: if the close code
is invalid
"""
if not (code in EXTERNAL_CLOSE_CODES or 3000 <= code < 5000):
raise ProtocolError("invalid status code")
# at the bottom to allow circular import, because Extension depends on Frame
import websockets.extensions.base # isort:skip # noqa
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 011453 x ustar 00 0000000 0000000 22 mtime=1571084468.0
websockets-8.1/src/websockets/handshake.py 0000644 0000765 0000024 00000014010 00000000000 020713 0 ustar 00myk staff 0000000 0000000 """
:mod:`websockets.handshake` provides helpers for the WebSocket handshake.
See `section 4 of RFC 6455`_.
.. _section 4 of RFC 6455: http://tools.ietf.org/html/rfc6455#section-4
Some checks cannot be performed because they depend too much on the
context; instead, they're documented below.
To accept a connection, a server must:
- Read the request, check that the method is GET, and check the headers with
:func:`check_request`,
- Send a 101 response to the client with the headers created by
:func:`build_response` if the request is valid; otherwise, send an
appropriate HTTP error code.
To open a connection, a client must:
- Send a GET request to the server with the headers created by
:func:`build_request`,
- Read the response, check that the status code is 101, and check the headers
with :func:`check_response`.
"""
import base64
import binascii
import hashlib
import random
from typing import List
from .exceptions import InvalidHeader, InvalidHeaderValue, InvalidUpgrade
from .headers import ConnectionOption, UpgradeProtocol, parse_connection, parse_upgrade
from .http import Headers, MultipleValuesError
__all__ = ["build_request", "check_request", "build_response", "check_response"]
GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
def build_request(headers: Headers) -> str:
"""
Build a handshake request to send to the server.
Update request headers passed in argument.
:param headers: request headers
:returns: ``key`` which must be passed to :func:`check_response`
"""
raw_key = bytes(random.getrandbits(8) for _ in range(16))
key = base64.b64encode(raw_key).decode()
headers["Upgrade"] = "websocket"
headers["Connection"] = "Upgrade"
headers["Sec-WebSocket-Key"] = key
headers["Sec-WebSocket-Version"] = "13"
return key
def check_request(headers: Headers) -> str:
"""
Check a handshake request received from the client.
This function doesn't verify that the request is an HTTP/1.1 or higher GET
request and doesn't perform ``Host`` and ``Origin`` checks. These controls
are usually performed earlier in the HTTP request handling code. They're
the responsibility of the caller.
:param headers: request headers
:returns: ``key`` which must be passed to :func:`build_response`
:raises ~websockets.exceptions.InvalidHandshake: if the handshake request
is invalid; then the server must return 400 Bad Request error
"""
connection: List[ConnectionOption] = sum(
[parse_connection(value) for value in headers.get_all("Connection")], []
)
if not any(value.lower() == "upgrade" for value in connection):
raise InvalidUpgrade("Connection", ", ".join(connection))
upgrade: List[UpgradeProtocol] = sum(
[parse_upgrade(value) for value in headers.get_all("Upgrade")], []
)
# For compatibility with non-strict implementations, ignore case when
# checking the Upgrade header. It's supposed to be 'WebSocket'.
if not (len(upgrade) == 1 and upgrade[0].lower() == "websocket"):
raise InvalidUpgrade("Upgrade", ", ".join(upgrade))
try:
s_w_key = headers["Sec-WebSocket-Key"]
except KeyError:
raise InvalidHeader("Sec-WebSocket-Key")
except MultipleValuesError:
raise InvalidHeader(
"Sec-WebSocket-Key", "more than one Sec-WebSocket-Key header found"
)
try:
raw_key = base64.b64decode(s_w_key.encode(), validate=True)
except binascii.Error:
raise InvalidHeaderValue("Sec-WebSocket-Key", s_w_key)
if len(raw_key) != 16:
raise InvalidHeaderValue("Sec-WebSocket-Key", s_w_key)
try:
s_w_version = headers["Sec-WebSocket-Version"]
except KeyError:
raise InvalidHeader("Sec-WebSocket-Version")
except MultipleValuesError:
raise InvalidHeader(
"Sec-WebSocket-Version", "more than one Sec-WebSocket-Version header found"
)
if s_w_version != "13":
raise InvalidHeaderValue("Sec-WebSocket-Version", s_w_version)
return s_w_key
def build_response(headers: Headers, key: str) -> None:
"""
Build a handshake response to send to the client.
Update response headers passed in argument.
:param headers: response headers
:param key: comes from :func:`check_request`
"""
headers["Upgrade"] = "websocket"
headers["Connection"] = "Upgrade"
headers["Sec-WebSocket-Accept"] = accept(key)
def check_response(headers: Headers, key: str) -> None:
"""
Check a handshake response received from the server.
This function doesn't verify that the response is an HTTP/1.1 or higher
response with a 101 status code. These controls are the responsibility of
the caller.
:param headers: response headers
:param key: comes from :func:`build_request`
:raises ~websockets.exceptions.InvalidHandshake: if the handshake response
is invalid
"""
connection: List[ConnectionOption] = sum(
[parse_connection(value) for value in headers.get_all("Connection")], []
)
if not any(value.lower() == "upgrade" for value in connection):
raise InvalidUpgrade("Connection", " ".join(connection))
upgrade: List[UpgradeProtocol] = sum(
[parse_upgrade(value) for value in headers.get_all("Upgrade")], []
)
# For compatibility with non-strict implementations, ignore case when
# checking the Upgrade header. It's supposed to be 'WebSocket'.
if not (len(upgrade) == 1 and upgrade[0].lower() == "websocket"):
raise InvalidUpgrade("Upgrade", ", ".join(upgrade))
try:
s_w_accept = headers["Sec-WebSocket-Accept"]
except KeyError:
raise InvalidHeader("Sec-WebSocket-Accept")
except MultipleValuesError:
raise InvalidHeader(
"Sec-WebSocket-Accept", "more than one Sec-WebSocket-Accept header found"
)
if s_w_accept != accept(key):
raise InvalidHeaderValue("Sec-WebSocket-Accept", s_w_accept)
def accept(key: str) -> str:
sha1 = hashlib.sha1((key + GUID).encode()).digest()
return base64.b64encode(sha1).decode()
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 011453 x ustar 00 0000000 0000000 22 mtime=1572601751.0
websockets-8.1/src/websockets/headers.py 0000644 0000765 0000024 00000035335 00000000000 020415 0 ustar 00myk staff 0000000 0000000 """
:mod:`websockets.headers` provides parsers and serializers for HTTP headers
used in WebSocket handshake messages.
These APIs cannot be imported from :mod:`websockets`. They must be imported
from :mod:`websockets.headers`.
"""
import base64
import binascii
import re
from typing import Callable, List, NewType, Optional, Sequence, Tuple, TypeVar, cast
from .exceptions import InvalidHeaderFormat, InvalidHeaderValue
from .typing import ExtensionHeader, ExtensionName, ExtensionParameter, Subprotocol
__all__ = [
"parse_connection",
"parse_upgrade",
"parse_extension",
"build_extension",
"parse_subprotocol",
"build_subprotocol",
"build_www_authenticate_basic",
"parse_authorization_basic",
"build_authorization_basic",
]
T = TypeVar("T")
ConnectionOption = NewType("ConnectionOption", str)
UpgradeProtocol = NewType("UpgradeProtocol", str)
# To avoid a dependency on a parsing library, we implement manually the ABNF
# described in https://tools.ietf.org/html/rfc6455#section-9.1 with the
# definitions from https://tools.ietf.org/html/rfc7230#appendix-B.
def peek_ahead(header: str, pos: int) -> Optional[str]:
"""
Return the next character from ``header`` at the given position.
Return ``None`` at the end of ``header``.
We never need to peek more than one character ahead.
"""
return None if pos == len(header) else header[pos]
_OWS_re = re.compile(r"[\t ]*")
def parse_OWS(header: str, pos: int) -> int:
"""
Parse optional whitespace from ``header`` at the given position.
Return the new position.
The whitespace itself isn't returned because it isn't significant.
"""
# There's always a match, possibly empty, whose content doesn't matter.
match = _OWS_re.match(header, pos)
assert match is not None
return match.end()
_token_re = re.compile(r"[-!#$%&\'*+.^_`|~0-9a-zA-Z]+")
def parse_token(header: str, pos: int, header_name: str) -> Tuple[str, int]:
"""
Parse a token from ``header`` at the given position.
Return the token value and the new position.
:raises ~websockets.exceptions.InvalidHeaderFormat: on invalid inputs.
"""
match = _token_re.match(header, pos)
if match is None:
raise InvalidHeaderFormat(header_name, "expected token", header, pos)
return match.group(), match.end()
_quoted_string_re = re.compile(
r'"(?:[\x09\x20-\x21\x23-\x5b\x5d-\x7e]|\\[\x09\x20-\x7e\x80-\xff])*"'
)
_unquote_re = re.compile(r"\\([\x09\x20-\x7e\x80-\xff])")
def parse_quoted_string(header: str, pos: int, header_name: str) -> Tuple[str, int]:
"""
Parse a quoted string from ``header`` at the given position.
Return the unquoted value and the new position.
:raises ~websockets.exceptions.InvalidHeaderFormat: on invalid inputs.
"""
match = _quoted_string_re.match(header, pos)
if match is None:
raise InvalidHeaderFormat(header_name, "expected quoted string", header, pos)
return _unquote_re.sub(r"\1", match.group()[1:-1]), match.end()
_quotable_re = re.compile(r"[\x09\x20-\x7e\x80-\xff]*")
_quote_re = re.compile(r"([\x22\x5c])")
def build_quoted_string(value: str) -> str:
"""
Format ``value`` as a quoted string.
This is the reverse of :func:`parse_quoted_string`.
"""
match = _quotable_re.fullmatch(value)
if match is None:
raise ValueError("invalid characters for quoted-string encoding")
return '"' + _quote_re.sub(r"\\\1", value) + '"'
def parse_list(
parse_item: Callable[[str, int, str], Tuple[T, int]],
header: str,
pos: int,
header_name: str,
) -> List[T]:
"""
Parse a comma-separated list from ``header`` at the given position.
This is appropriate for parsing values with the following grammar:
1#item
``parse_item`` parses one item.
``header`` is assumed not to start or end with whitespace.
(This function is designed for parsing an entire header value and
:func:`~websockets.http.read_headers` strips whitespace from values.)
Return a list of items.
:raises ~websockets.exceptions.InvalidHeaderFormat: on invalid inputs.
"""
# Per https://tools.ietf.org/html/rfc7230#section-7, "a recipient MUST
# parse and ignore a reasonable number of empty list elements"; hence
# while loops that remove extra delimiters.
# Remove extra delimiters before the first item.
while peek_ahead(header, pos) == ",":
pos = parse_OWS(header, pos + 1)
items = []
while True:
# Loop invariant: a item starts at pos in header.
item, pos = parse_item(header, pos, header_name)
items.append(item)
pos = parse_OWS(header, pos)
# We may have reached the end of the header.
if pos == len(header):
break
# There must be a delimiter after each element except the last one.
if peek_ahead(header, pos) == ",":
pos = parse_OWS(header, pos + 1)
else:
raise InvalidHeaderFormat(header_name, "expected comma", header, pos)
# Remove extra delimiters before the next item.
while peek_ahead(header, pos) == ",":
pos = parse_OWS(header, pos + 1)
# We may have reached the end of the header.
if pos == len(header):
break
# Since we only advance in the header by one character with peek_ahead()
# or with the end position of a regex match, we can't overshoot the end.
assert pos == len(header)
return items
def parse_connection_option(
header: str, pos: int, header_name: str
) -> Tuple[ConnectionOption, int]:
"""
Parse a Connection option from ``header`` at the given position.
Return the protocol value and the new position.
:raises ~websockets.exceptions.InvalidHeaderFormat: on invalid inputs.
"""
item, pos = parse_token(header, pos, header_name)
return cast(ConnectionOption, item), pos
def parse_connection(header: str) -> List[ConnectionOption]:
"""
Parse a ``Connection`` header.
Return a list of HTTP connection options.
:param header: value of the ``Connection`` header
:raises ~websockets.exceptions.InvalidHeaderFormat: on invalid inputs.
"""
return parse_list(parse_connection_option, header, 0, "Connection")
_protocol_re = re.compile(
r"[-!#$%&\'*+.^_`|~0-9a-zA-Z]+(?:/[-!#$%&\'*+.^_`|~0-9a-zA-Z]+)?"
)
def parse_upgrade_protocol(
header: str, pos: int, header_name: str
) -> Tuple[UpgradeProtocol, int]:
"""
Parse an Upgrade protocol from ``header`` at the given position.
Return the protocol value and the new position.
:raises ~websockets.exceptions.InvalidHeaderFormat: on invalid inputs.
"""
match = _protocol_re.match(header, pos)
if match is None:
raise InvalidHeaderFormat(header_name, "expected protocol", header, pos)
return cast(UpgradeProtocol, match.group()), match.end()
def parse_upgrade(header: str) -> List[UpgradeProtocol]:
"""
Parse an ``Upgrade`` header.
Return a list of HTTP protocols.
:param header: value of the ``Upgrade`` header
:raises ~websockets.exceptions.InvalidHeaderFormat: on invalid inputs.
"""
return parse_list(parse_upgrade_protocol, header, 0, "Upgrade")
def parse_extension_item_param(
header: str, pos: int, header_name: str
) -> Tuple[ExtensionParameter, int]:
"""
Parse a single extension parameter from ``header`` at the given position.
Return a ``(name, value)`` pair and the new position.
:raises ~websockets.exceptions.InvalidHeaderFormat: on invalid inputs.
"""
# Extract parameter name.
name, pos = parse_token(header, pos, header_name)
pos = parse_OWS(header, pos)
# Extract parameter value, if there is one.
value: Optional[str] = None
if peek_ahead(header, pos) == "=":
pos = parse_OWS(header, pos + 1)
if peek_ahead(header, pos) == '"':
pos_before = pos # for proper error reporting below
value, pos = parse_quoted_string(header, pos, header_name)
# https://tools.ietf.org/html/rfc6455#section-9.1 says: the value
# after quoted-string unescaping MUST conform to the 'token' ABNF.
if _token_re.fullmatch(value) is None:
raise InvalidHeaderFormat(
header_name, "invalid quoted header content", header, pos_before
)
else:
value, pos = parse_token(header, pos, header_name)
pos = parse_OWS(header, pos)
return (name, value), pos
def parse_extension_item(
header: str, pos: int, header_name: str
) -> Tuple[ExtensionHeader, int]:
"""
Parse an extension definition from ``header`` at the given position.
Return an ``(extension name, parameters)`` pair, where ``parameters`` is a
list of ``(name, value)`` pairs, and the new position.
:raises ~websockets.exceptions.InvalidHeaderFormat: on invalid inputs.
"""
# Extract extension name.
name, pos = parse_token(header, pos, header_name)
pos = parse_OWS(header, pos)
# Extract all parameters.
parameters = []
while peek_ahead(header, pos) == ";":
pos = parse_OWS(header, pos + 1)
parameter, pos = parse_extension_item_param(header, pos, header_name)
parameters.append(parameter)
return (cast(ExtensionName, name), parameters), pos
def parse_extension(header: str) -> List[ExtensionHeader]:
"""
Parse a ``Sec-WebSocket-Extensions`` header.
Return a list of WebSocket extensions and their parameters in this format::
[
(
'extension name',
[
('parameter name', 'parameter value'),
....
]
),
...
]
Parameter values are ``None`` when no value is provided.
:raises ~websockets.exceptions.InvalidHeaderFormat: on invalid inputs.
"""
return parse_list(parse_extension_item, header, 0, "Sec-WebSocket-Extensions")
parse_extension_list = parse_extension # alias for backwards compatibility
def build_extension_item(
name: ExtensionName, parameters: List[ExtensionParameter]
) -> str:
"""
Build an extension definition.
This is the reverse of :func:`parse_extension_item`.
"""
return "; ".join(
[cast(str, name)]
+ [
# Quoted strings aren't necessary because values are always tokens.
name if value is None else f"{name}={value}"
for name, value in parameters
]
)
def build_extension(extensions: Sequence[ExtensionHeader]) -> str:
"""
Build a ``Sec-WebSocket-Extensions`` header.
This is the reverse of :func:`parse_extension`.
"""
return ", ".join(
build_extension_item(name, parameters) for name, parameters in extensions
)
build_extension_list = build_extension # alias for backwards compatibility
def parse_subprotocol_item(
header: str, pos: int, header_name: str
) -> Tuple[Subprotocol, int]:
"""
Parse a subprotocol from ``header`` at the given position.
Return the subprotocol value and the new position.
:raises ~websockets.exceptions.InvalidHeaderFormat: on invalid inputs.
"""
item, pos = parse_token(header, pos, header_name)
return cast(Subprotocol, item), pos
def parse_subprotocol(header: str) -> List[Subprotocol]:
"""
Parse a ``Sec-WebSocket-Protocol`` header.
Return a list of WebSocket subprotocols.
:raises ~websockets.exceptions.InvalidHeaderFormat: on invalid inputs.
"""
return parse_list(parse_subprotocol_item, header, 0, "Sec-WebSocket-Protocol")
parse_subprotocol_list = parse_subprotocol # alias for backwards compatibility
def build_subprotocol(protocols: Sequence[Subprotocol]) -> str:
"""
Build a ``Sec-WebSocket-Protocol`` header.
This is the reverse of :func:`parse_subprotocol`.
"""
return ", ".join(protocols)
build_subprotocol_list = build_subprotocol # alias for backwards compatibility
def build_www_authenticate_basic(realm: str) -> str:
"""
Build a ``WWW-Authenticate`` header for HTTP Basic Auth.
:param realm: authentication realm
"""
# https://tools.ietf.org/html/rfc7617#section-2
realm = build_quoted_string(realm)
charset = build_quoted_string("UTF-8")
return f"Basic realm={realm}, charset={charset}"
_token68_re = re.compile(r"[A-Za-z0-9-._~+/]+=*")
def parse_token68(header: str, pos: int, header_name: str) -> Tuple[str, int]:
"""
Parse a token68 from ``header`` at the given position.
Return the token value and the new position.
:raises ~websockets.exceptions.InvalidHeaderFormat: on invalid inputs.
"""
match = _token68_re.match(header, pos)
if match is None:
raise InvalidHeaderFormat(header_name, "expected token68", header, pos)
return match.group(), match.end()
def parse_end(header: str, pos: int, header_name: str) -> None:
"""
Check that parsing reached the end of header.
"""
if pos < len(header):
raise InvalidHeaderFormat(header_name, "trailing data", header, pos)
def parse_authorization_basic(header: str) -> Tuple[str, str]:
"""
Parse an ``Authorization`` header for HTTP Basic Auth.
Return a ``(username, password)`` tuple.
:param header: value of the ``Authorization`` header
:raises InvalidHeaderFormat: on invalid inputs
:raises InvalidHeaderValue: on unsupported inputs
"""
# https://tools.ietf.org/html/rfc7235#section-2.1
# https://tools.ietf.org/html/rfc7617#section-2
scheme, pos = parse_token(header, 0, "Authorization")
if scheme.lower() != "basic":
raise InvalidHeaderValue("Authorization", f"unsupported scheme: {scheme}")
if peek_ahead(header, pos) != " ":
raise InvalidHeaderFormat(
"Authorization", "expected space after scheme", header, pos
)
pos += 1
basic_credentials, pos = parse_token68(header, pos, "Authorization")
parse_end(header, pos, "Authorization")
try:
user_pass = base64.b64decode(basic_credentials.encode()).decode()
except binascii.Error:
raise InvalidHeaderValue(
"Authorization", "expected base64-encoded credentials"
) from None
try:
username, password = user_pass.split(":", 1)
except ValueError:
raise InvalidHeaderValue(
"Authorization", "expected username:password credentials"
) from None
return username, password
def build_authorization_basic(username: str, password: str) -> str:
"""
Build an ``Authorization`` header for HTTP Basic Auth.
This is the reverse of :func:`parse_authorization_basic`.
"""
# https://tools.ietf.org/html/rfc7617#section-2
assert ":" not in username
user_pass = f"{username}:{password}"
basic_credentials = base64.b64encode(user_pass.encode()).decode()
return "Basic " + basic_credentials
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 011453 x ustar 00 0000000 0000000 22 mtime=1571084468.0
websockets-8.1/src/websockets/http.py 0000644 0000765 0000024 00000027062 00000000000 017757 0 ustar 00myk staff 0000000 0000000 """
:mod:`websockets.http` module provides basic HTTP/1.1 support. It is merely
:adequate for WebSocket handshake messages.
These APIs cannot be imported from :mod:`websockets`. They must be imported
from :mod:`websockets.http`.
"""
import asyncio
import re
import sys
from typing import (
Any,
Dict,
Iterable,
Iterator,
List,
Mapping,
MutableMapping,
Tuple,
Union,
)
from .version import version as websockets_version
__all__ = [
"read_request",
"read_response",
"Headers",
"MultipleValuesError",
"USER_AGENT",
]
MAX_HEADERS = 256
MAX_LINE = 4096
USER_AGENT = f"Python/{sys.version[:3]} websockets/{websockets_version}"
def d(value: bytes) -> str:
"""
Decode a bytestring for interpolating into an error message.
"""
return value.decode(errors="backslashreplace")
# See https://tools.ietf.org/html/rfc7230#appendix-B.
# Regex for validating header names.
_token_re = re.compile(rb"[-!#$%&\'*+.^_`|~0-9a-zA-Z]+")
# Regex for validating header values.
# We don't attempt to support obsolete line folding.
# Include HTAB (\x09), SP (\x20), VCHAR (\x21-\x7e), obs-text (\x80-\xff).
# The ABNF is complicated because it attempts to express that optional
# whitespace is ignored. We strip whitespace and don't revalidate that.
# See also https://www.rfc-editor.org/errata_search.php?rfc=7230&eid=4189
_value_re = re.compile(rb"[\x09\x20-\x7e\x80-\xff]*")
async def read_request(stream: asyncio.StreamReader) -> Tuple[str, "Headers"]:
"""
Read an HTTP/1.1 GET request and return ``(path, headers)``.
``path`` isn't URL-decoded or validated in any way.
``path`` and ``headers`` are expected to contain only ASCII characters.
Other characters are represented with surrogate escapes.
:func:`read_request` doesn't attempt to read the request body because
WebSocket handshake requests don't have one. If the request contains a
body, it may be read from ``stream`` after this coroutine returns.
:param stream: input to read the request from
:raises EOFError: if the connection is closed without a full HTTP request
:raises SecurityError: if the request exceeds a security limit
:raises ValueError: if the request isn't well formatted
"""
# https://tools.ietf.org/html/rfc7230#section-3.1.1
# Parsing is simple because fixed values are expected for method and
# version and because path isn't checked. Since WebSocket software tends
# to implement HTTP/1.1 strictly, there's little need for lenient parsing.
try:
request_line = await read_line(stream)
except EOFError as exc:
raise EOFError("connection closed while reading HTTP request line") from exc
try:
method, raw_path, version = request_line.split(b" ", 2)
except ValueError: # not enough values to unpack (expected 3, got 1-2)
raise ValueError(f"invalid HTTP request line: {d(request_line)}") from None
if method != b"GET":
raise ValueError(f"unsupported HTTP method: {d(method)}")
if version != b"HTTP/1.1":
raise ValueError(f"unsupported HTTP version: {d(version)}")
path = raw_path.decode("ascii", "surrogateescape")
headers = await read_headers(stream)
return path, headers
async def read_response(stream: asyncio.StreamReader) -> Tuple[int, str, "Headers"]:
"""
Read an HTTP/1.1 response and return ``(status_code, reason, headers)``.
``reason`` and ``headers`` are expected to contain only ASCII characters.
Other characters are represented with surrogate escapes.
:func:`read_request` doesn't attempt to read the response body because
WebSocket handshake responses don't have one. If the response contains a
body, it may be read from ``stream`` after this coroutine returns.
:param stream: input to read the response from
:raises EOFError: if the connection is closed without a full HTTP response
:raises SecurityError: if the response exceeds a security limit
:raises ValueError: if the response isn't well formatted
"""
# https://tools.ietf.org/html/rfc7230#section-3.1.2
# As in read_request, parsing is simple because a fixed value is expected
# for version, status_code is a 3-digit number, and reason can be ignored.
try:
status_line = await read_line(stream)
except EOFError as exc:
raise EOFError("connection closed while reading HTTP status line") from exc
try:
version, raw_status_code, raw_reason = status_line.split(b" ", 2)
except ValueError: # not enough values to unpack (expected 3, got 1-2)
raise ValueError(f"invalid HTTP status line: {d(status_line)}") from None
if version != b"HTTP/1.1":
raise ValueError(f"unsupported HTTP version: {d(version)}")
try:
status_code = int(raw_status_code)
except ValueError: # invalid literal for int() with base 10
raise ValueError(f"invalid HTTP status code: {d(raw_status_code)}") from None
if not 100 <= status_code < 1000:
raise ValueError(f"unsupported HTTP status code: {d(raw_status_code)}")
if not _value_re.fullmatch(raw_reason):
raise ValueError(f"invalid HTTP reason phrase: {d(raw_reason)}")
reason = raw_reason.decode()
headers = await read_headers(stream)
return status_code, reason, headers
async def read_headers(stream: asyncio.StreamReader) -> "Headers":
"""
Read HTTP headers from ``stream``.
Non-ASCII characters are represented with surrogate escapes.
"""
# https://tools.ietf.org/html/rfc7230#section-3.2
# We don't attempt to support obsolete line folding.
headers = Headers()
for _ in range(MAX_HEADERS + 1):
try:
line = await read_line(stream)
except EOFError as exc:
raise EOFError("connection closed while reading HTTP headers") from exc
if line == b"":
break
try:
raw_name, raw_value = line.split(b":", 1)
except ValueError: # not enough values to unpack (expected 2, got 1)
raise ValueError(f"invalid HTTP header line: {d(line)}") from None
if not _token_re.fullmatch(raw_name):
raise ValueError(f"invalid HTTP header name: {d(raw_name)}")
raw_value = raw_value.strip(b" \t")
if not _value_re.fullmatch(raw_value):
raise ValueError(f"invalid HTTP header value: {d(raw_value)}")
name = raw_name.decode("ascii") # guaranteed to be ASCII at this point
value = raw_value.decode("ascii", "surrogateescape")
headers[name] = value
else:
raise websockets.exceptions.SecurityError("too many HTTP headers")
return headers
async def read_line(stream: asyncio.StreamReader) -> bytes:
"""
Read a single line from ``stream``.
CRLF is stripped from the return value.
"""
# Security: this is bounded by the StreamReader's limit (default = 32 KiB).
line = await stream.readline()
# Security: this guarantees header values are small (hard-coded = 4 KiB)
if len(line) > MAX_LINE:
raise websockets.exceptions.SecurityError("line too long")
# Not mandatory but safe - https://tools.ietf.org/html/rfc7230#section-3.5
if not line.endswith(b"\r\n"):
raise EOFError("line without CRLF")
return line[:-2]
class MultipleValuesError(LookupError):
"""
Exception raised when :class:`Headers` has more than one value for a key.
"""
def __str__(self) -> str:
# Implement the same logic as KeyError_str in Objects/exceptions.c.
if len(self.args) == 1:
return repr(self.args[0])
return super().__str__()
class Headers(MutableMapping[str, str]):
"""
Efficient data structure for manipulating HTTP headers.
A :class:`list` of ``(name, values)`` is inefficient for lookups.
A :class:`dict` doesn't suffice because header names are case-insensitive
and multiple occurrences of headers with the same name are possible.
:class:`Headers` stores HTTP headers in a hybrid data structure to provide
efficient insertions and lookups while preserving the original data.
In order to account for multiple values with minimal hassle,
:class:`Headers` follows this logic:
- When getting a header with ``headers[name]``:
- if there's no value, :exc:`KeyError` is raised;
- if there's exactly one value, it's returned;
- if there's more than one value, :exc:`MultipleValuesError` is raised.
- When setting a header with ``headers[name] = value``, the value is
appended to the list of values for that header.
- When deleting a header with ``del headers[name]``, all values for that
header are removed (this is slow).
Other methods for manipulating headers are consistent with this logic.
As long as no header occurs multiple times, :class:`Headers` behaves like
:class:`dict`, except keys are lower-cased to provide case-insensitivity.
Two methods support support manipulating multiple values explicitly:
- :meth:`get_all` returns a list of all values for a header;
- :meth:`raw_items` returns an iterator of ``(name, values)`` pairs.
"""
__slots__ = ["_dict", "_list"]
def __init__(self, *args: Any, **kwargs: str) -> None:
self._dict: Dict[str, List[str]] = {}
self._list: List[Tuple[str, str]] = []
# MutableMapping.update calls __setitem__ for each (name, value) pair.
self.update(*args, **kwargs)
def __str__(self) -> str:
return "".join(f"{key}: {value}\r\n" for key, value in self._list) + "\r\n"
def __repr__(self) -> str:
return f"{self.__class__.__name__}({self._list!r})"
def copy(self) -> "Headers":
copy = self.__class__()
copy._dict = self._dict.copy()
copy._list = self._list.copy()
return copy
# Collection methods
def __contains__(self, key: object) -> bool:
return isinstance(key, str) and key.lower() in self._dict
def __iter__(self) -> Iterator[str]:
return iter(self._dict)
def __len__(self) -> int:
return len(self._dict)
# MutableMapping methods
def __getitem__(self, key: str) -> str:
value = self._dict[key.lower()]
if len(value) == 1:
return value[0]
else:
raise MultipleValuesError(key)
def __setitem__(self, key: str, value: str) -> None:
self._dict.setdefault(key.lower(), []).append(value)
self._list.append((key, value))
def __delitem__(self, key: str) -> None:
key_lower = key.lower()
self._dict.__delitem__(key_lower)
# This is inefficent. Fortunately deleting HTTP headers is uncommon.
self._list = [(k, v) for k, v in self._list if k.lower() != key_lower]
def __eq__(self, other: Any) -> bool:
if not isinstance(other, Headers):
return NotImplemented
return self._list == other._list
def clear(self) -> None:
"""
Remove all headers.
"""
self._dict = {}
self._list = []
# Methods for handling multiple values
def get_all(self, key: str) -> List[str]:
"""
Return the (possibly empty) list of all values for a header.
:param key: header name
"""
return self._dict.get(key.lower(), [])
def raw_items(self) -> Iterator[Tuple[str, str]]:
"""
Return an iterator of all values as ``(name, value)`` pairs.
"""
return iter(self._list)
HeadersLike = Union[Headers, Mapping[str, str], Iterable[Tuple[str, str]]]
# at the bottom to allow circular import, because AbortHandshake depends on HeadersLike
import websockets.exceptions # isort:skip # noqa
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 011453 x ustar 00 0000000 0000000 22 mtime=1571084468.0
websockets-8.1/src/websockets/protocol.py 0000644 0000765 0000024 00000153366 00000000000 020650 0 ustar 00myk staff 0000000 0000000 """
:mod:`websockets.protocol` handles WebSocket control and data frames.
See `sections 4 to 8 of RFC 6455`_.
.. _sections 4 to 8 of RFC 6455: http://tools.ietf.org/html/rfc6455#section-4
"""
import asyncio
import codecs
import collections
import enum
import logging
import random
import struct
import sys
import warnings
from typing import (
Any,
AsyncIterable,
AsyncIterator,
Awaitable,
Deque,
Dict,
Iterable,
List,
Optional,
Union,
cast,
)
from .exceptions import (
ConnectionClosed,
ConnectionClosedError,
ConnectionClosedOK,
InvalidState,
PayloadTooBig,
ProtocolError,
)
from .extensions.base import Extension
from .framing import *
from .handshake import *
from .http import Headers
from .typing import Data
__all__ = ["WebSocketCommonProtocol"]
logger = logging.getLogger(__name__)
# A WebSocket connection goes through the following four states, in order:
class State(enum.IntEnum):
CONNECTING, OPEN, CLOSING, CLOSED = range(4)
# In order to ensure consistency, the code always checks the current value of
# WebSocketCommonProtocol.state before assigning a new value and never yields
# between the check and the assignment.
class WebSocketCommonProtocol(asyncio.Protocol):
"""
:class:`~asyncio.Protocol` subclass implementing the data transfer phase.
Once the WebSocket connection is established, during the data transfer
phase, the protocol is almost symmetrical between the server side and the
client side. :class:`WebSocketCommonProtocol` implements logic that's
shared between servers and clients..
Subclasses such as :class:`~websockets.server.WebSocketServerProtocol` and
:class:`~websockets.client.WebSocketClientProtocol` implement the opening
handshake, which is different between servers and clients.
:class:`WebSocketCommonProtocol` performs four functions:
* It runs a task that stores incoming data frames in a queue and makes
them available with the :meth:`recv` coroutine.
* It sends outgoing data frames with the :meth:`send` coroutine.
* It deals with control frames automatically.
* It performs the closing handshake.
:class:`WebSocketCommonProtocol` supports asynchronous iteration::
async for message in websocket:
await process(message)
The iterator yields incoming messages. It exits normally when the
connection is closed with the close code 1000 (OK) or 1001 (going away).
It raises a :exc:`~websockets.exceptions.ConnectionClosedError` exception
when the connection is closed with any other code.
Once the connection is open, a `Ping frame`_ is sent every
``ping_interval`` seconds. This serves as a keepalive. It helps keeping
the connection open, especially in the presence of proxies with short
timeouts on inactive connections. Set ``ping_interval`` to ``None`` to
disable this behavior.
.. _Ping frame: https://tools.ietf.org/html/rfc6455#section-5.5.2
If the corresponding `Pong frame`_ isn't received within ``ping_timeout``
seconds, the connection is considered unusable and is closed with
code 1011. This ensures that the remote endpoint remains responsive. Set
``ping_timeout`` to ``None`` to disable this behavior.
.. _Pong frame: https://tools.ietf.org/html/rfc6455#section-5.5.3
The ``close_timeout`` parameter defines a maximum wait time in seconds for
completing the closing handshake and terminating the TCP connection.
:meth:`close` completes in at most ``4 * close_timeout`` on the server
side and ``5 * close_timeout`` on the client side.
``close_timeout`` needs to be a parameter of the protocol because
``websockets`` usually calls :meth:`close` implicitly:
- on the server side, when the connection handler terminates,
- on the client side, when exiting the context manager for the connection.
To apply a timeout to any other API, wrap it in :func:`~asyncio.wait_for`.
The ``max_size`` parameter enforces the maximum size for incoming messages
in bytes. The default value is 1 MiB. ``None`` disables the limit. If a
message larger than the maximum size is received, :meth:`recv` will
raise :exc:`~websockets.exceptions.ConnectionClosedError` and the
connection will be closed with code 1009.
The ``max_queue`` parameter sets the maximum length of the queue that
holds incoming messages. The default value is ``32``. ``None`` disables
the limit. Messages are added to an in-memory queue when they're received;
then :meth:`recv` pops from that queue. In order to prevent excessive
memory consumption when messages are received faster than they can be
processed, the queue must be bounded. If the queue fills up, the protocol
stops processing incoming data until :meth:`recv` is called. In this
situation, various receive buffers (at least in ``asyncio`` and in the OS)
will fill up, then the TCP receive window will shrink, slowing down
transmission to avoid packet loss.
Since Python can use up to 4 bytes of memory to represent a single
character, each connection may use up to ``4 * max_size * max_queue``
bytes of memory to store incoming messages. By default, this is 128 MiB.
You may want to lower the limits, depending on your application's
requirements.
The ``read_limit`` argument sets the high-water limit of the buffer for
incoming bytes. The low-water limit is half the high-water limit. The
default value is 64 KiB, half of asyncio's default (based on the current
implementation of :class:`~asyncio.StreamReader`).
The ``write_limit`` argument sets the high-water limit of the buffer for
outgoing bytes. The low-water limit is a quarter of the high-water limit.
The default value is 64 KiB, equal to asyncio's default (based on the
current implementation of ``FlowControlMixin``).
As soon as the HTTP request and response in the opening handshake are
processed:
* the request path is available in the :attr:`path` attribute;
* the request and response HTTP headers are available in the
:attr:`request_headers` and :attr:`response_headers` attributes,
which are :class:`~websockets.http.Headers` instances.
If a subprotocol was negotiated, it's available in the :attr:`subprotocol`
attribute.
Once the connection is closed, the code is available in the
:attr:`close_code` attribute and the reason in :attr:`close_reason`.
All these attributes must be treated as read-only.
"""
# There are only two differences between the client-side and server-side
# behavior: masking the payload and closing the underlying TCP connection.
# Set is_client = True/False and side = "client"/"server" to pick a side.
is_client: bool
side: str = "undefined"
def __init__(
self,
*,
ping_interval: Optional[float] = 20,
ping_timeout: Optional[float] = 20,
close_timeout: Optional[float] = None,
max_size: Optional[int] = 2 ** 20,
max_queue: Optional[int] = 2 ** 5,
read_limit: int = 2 ** 16,
write_limit: int = 2 ** 16,
loop: Optional[asyncio.AbstractEventLoop] = None,
# The following arguments are kept only for backwards compatibility.
host: Optional[str] = None,
port: Optional[int] = None,
secure: Optional[bool] = None,
legacy_recv: bool = False,
timeout: Optional[float] = None,
) -> None:
# Backwards compatibility: close_timeout used to be called timeout.
if timeout is None:
timeout = 10
else:
warnings.warn("rename timeout to close_timeout", DeprecationWarning)
# If both are specified, timeout is ignored.
if close_timeout is None:
close_timeout = timeout
self.ping_interval = ping_interval
self.ping_timeout = ping_timeout
self.close_timeout = close_timeout
self.max_size = max_size
self.max_queue = max_queue
self.read_limit = read_limit
self.write_limit = write_limit
if loop is None:
loop = asyncio.get_event_loop()
self.loop = loop
self._host = host
self._port = port
self._secure = secure
self.legacy_recv = legacy_recv
# Configure read buffer limits. The high-water limit is defined by
# ``self.read_limit``. The ``limit`` argument controls the line length
# limit and half the buffer limit of :class:`~asyncio.StreamReader`.
# That's why it must be set to half of ``self.read_limit``.
self.reader = asyncio.StreamReader(limit=read_limit // 2, loop=loop)
# Copied from asyncio.FlowControlMixin
self._paused = False
self._drain_waiter: Optional[asyncio.Future[None]] = None
self._drain_lock = asyncio.Lock(
loop=loop if sys.version_info[:2] < (3, 8) else None
)
# This class implements the data transfer and closing handshake, which
# are shared between the client-side and the server-side.
# Subclasses implement the opening handshake and, on success, execute
# :meth:`connection_open` to change the state to OPEN.
self.state = State.CONNECTING
logger.debug("%s - state = CONNECTING", self.side)
# HTTP protocol parameters.
self.path: str
self.request_headers: Headers
self.response_headers: Headers
# WebSocket protocol parameters.
self.extensions: List[Extension] = []
self.subprotocol: Optional[str] = None
# The close code and reason are set when receiving a close frame or
# losing the TCP connection.
self.close_code: int
self.close_reason: str
# Completed when the connection state becomes CLOSED. Translates the
# :meth:`connection_lost` callback to a :class:`~asyncio.Future`
# that can be awaited. (Other :class:`~asyncio.Protocol` callbacks are
# translated by ``self.stream_reader``).
self.connection_lost_waiter: asyncio.Future[None] = loop.create_future()
# Queue of received messages.
self.messages: Deque[Data] = collections.deque()
self._pop_message_waiter: Optional[asyncio.Future[None]] = None
self._put_message_waiter: Optional[asyncio.Future[None]] = None
# Protect sending fragmented messages.
self._fragmented_message_waiter: Optional[asyncio.Future[None]] = None
# Mapping of ping IDs to waiters, in chronological order.
self.pings: Dict[bytes, asyncio.Future[None]] = {}
# Task running the data transfer.
self.transfer_data_task: asyncio.Task[None]
# Exception that occurred during data transfer, if any.
self.transfer_data_exc: Optional[BaseException] = None
# Task sending keepalive pings.
self.keepalive_ping_task: asyncio.Task[None]
# Task closing the TCP connection.
self.close_connection_task: asyncio.Task[None]
# Copied from asyncio.FlowControlMixin
async def _drain_helper(self) -> None: # pragma: no cover
if self.connection_lost_waiter.done():
raise ConnectionResetError("Connection lost")
if not self._paused:
return
waiter = self._drain_waiter
assert waiter is None or waiter.cancelled()
waiter = self.loop.create_future()
self._drain_waiter = waiter
await waiter
# Copied from asyncio.StreamWriter
async def _drain(self) -> None: # pragma: no cover
if self.reader is not None:
exc = self.reader.exception()
if exc is not None:
raise exc
if self.transport is not None:
if self.transport.is_closing():
# Yield to the event loop so connection_lost() may be
# called. Without this, _drain_helper() would return
# immediately, and code that calls
# write(...); yield from drain()
# in a loop would never call connection_lost(), so it
# would not see an error when the socket is closed.
await asyncio.sleep(
0, loop=self.loop if sys.version_info[:2] < (3, 8) else None
)
await self._drain_helper()
def connection_open(self) -> None:
"""
Callback when the WebSocket opening handshake completes.
Enter the OPEN state and start the data transfer phase.
"""
# 4.1. The WebSocket Connection is Established.
assert self.state is State.CONNECTING
self.state = State.OPEN
logger.debug("%s - state = OPEN", self.side)
# Start the task that receives incoming WebSocket messages.
self.transfer_data_task = self.loop.create_task(self.transfer_data())
# Start the task that sends pings at regular intervals.
self.keepalive_ping_task = self.loop.create_task(self.keepalive_ping())
# Start the task that eventually closes the TCP connection.
self.close_connection_task = self.loop.create_task(self.close_connection())
@property
def host(self) -> Optional[str]:
alternative = "remote_address" if self.is_client else "local_address"
warnings.warn(f"use {alternative}[0] instead of host", DeprecationWarning)
return self._host
@property
def port(self) -> Optional[int]:
alternative = "remote_address" if self.is_client else "local_address"
warnings.warn(f"use {alternative}[1] instead of port", DeprecationWarning)
return self._port
@property
def secure(self) -> Optional[bool]:
warnings.warn(f"don't use secure", DeprecationWarning)
return self._secure
# Public API
@property
def local_address(self) -> Any:
"""
Local address of the connection.
This is a ``(host, port)`` tuple or ``None`` if the connection hasn't
been established yet.
"""
try:
transport = self.transport
except AttributeError:
return None
else:
return transport.get_extra_info("sockname")
@property
def remote_address(self) -> Any:
"""
Remote address of the connection.
This is a ``(host, port)`` tuple or ``None`` if the connection hasn't
been established yet.
"""
try:
transport = self.transport
except AttributeError:
return None
else:
return transport.get_extra_info("peername")
@property
def open(self) -> bool:
"""
``True`` when the connection is usable.
It may be used to detect disconnections. However, this approach is
discouraged per the EAFP_ principle.
When ``open`` is ``False``, using the connection raises a
:exc:`~websockets.exceptions.ConnectionClosed` exception.
.. _EAFP: https://docs.python.org/3/glossary.html#term-eafp
"""
return self.state is State.OPEN and not self.transfer_data_task.done()
@property
def closed(self) -> bool:
"""
``True`` once the connection is closed.
Be aware that both :attr:`open` and :attr:`closed` are ``False`` during
the opening and closing sequences.
"""
return self.state is State.CLOSED
async def wait_closed(self) -> None:
"""
Wait until the connection is closed.
This is identical to :attr:`closed`, except it can be awaited.
This can make it easier to handle connection termination, regardless
of its cause, in tasks that interact with the WebSocket connection.
"""
await asyncio.shield(self.connection_lost_waiter)
async def __aiter__(self) -> AsyncIterator[Data]:
"""
Iterate on received messages.
Exit normally when the connection is closed with code 1000 or 1001.
Raise an exception in other cases.
"""
try:
while True:
yield await self.recv()
except ConnectionClosedOK:
return
async def recv(self) -> Data:
"""
Receive the next message.
Return a :class:`str` for a text frame and :class:`bytes` for a binary
frame.
When the end of the message stream is reached, :meth:`recv` raises
:exc:`~websockets.exceptions.ConnectionClosed`. Specifically, it
raises :exc:`~websockets.exceptions.ConnectionClosedOK` after a normal
connection closure and
:exc:`~websockets.exceptions.ConnectionClosedError` after a protocol
error or a network failure.
.. versionchanged:: 3.0
:meth:`recv` used to return ``None`` instead. Refer to the
changelog for details.
Canceling :meth:`recv` is safe. There's no risk of losing the next
message. The next invocation of :meth:`recv` will return it. This
makes it possible to enforce a timeout by wrapping :meth:`recv` in
:func:`~asyncio.wait_for`.
:raises ~websockets.exceptions.ConnectionClosed: when the
connection is closed
:raises RuntimeError: if two coroutines call :meth:`recv` concurrently
"""
if self._pop_message_waiter is not None:
raise RuntimeError(
"cannot call recv while another coroutine "
"is already waiting for the next message"
)
# Don't await self.ensure_open() here:
# - messages could be available in the queue even if the connection
# is closed;
# - messages could be received before the closing frame even if the
# connection is closing.
# Wait until there's a message in the queue (if necessary) or the
# connection is closed.
while len(self.messages) <= 0:
pop_message_waiter: asyncio.Future[None] = self.loop.create_future()
self._pop_message_waiter = pop_message_waiter
try:
# If asyncio.wait() is canceled, it doesn't cancel
# pop_message_waiter and self.transfer_data_task.
await asyncio.wait(
[pop_message_waiter, self.transfer_data_task],
loop=self.loop if sys.version_info[:2] < (3, 8) else None,
return_when=asyncio.FIRST_COMPLETED,
)
finally:
self._pop_message_waiter = None
# If asyncio.wait(...) exited because self.transfer_data_task
# completed before receiving a new message, raise a suitable
# exception (or return None if legacy_recv is enabled).
if not pop_message_waiter.done():
if self.legacy_recv:
return None # type: ignore
else:
# Wait until the connection is closed to raise
# ConnectionClosed with the correct code and reason.
await self.ensure_open()
# Pop a message from the queue.
message = self.messages.popleft()
# Notify transfer_data().
if self._put_message_waiter is not None:
self._put_message_waiter.set_result(None)
self._put_message_waiter = None
return message
async def send(
self, message: Union[Data, Iterable[Data], AsyncIterable[Data]]
) -> None:
"""
Send a message.
A string (:class:`str`) is sent as a `Text frame`_. A bytestring or
bytes-like object (:class:`bytes`, :class:`bytearray`, or
:class:`memoryview`) is sent as a `Binary frame`_.
.. _Text frame: https://tools.ietf.org/html/rfc6455#section-5.6
.. _Binary frame: https://tools.ietf.org/html/rfc6455#section-5.6
:meth:`send` also accepts an iterable or an asynchronous iterable of
strings, bytestrings, or bytes-like objects. In that case the message
is fragmented. Each item is treated as a message fragment and sent in
its own frame. All items must be of the same type, or else
:meth:`send` will raise a :exc:`TypeError` and the connection will be
closed.
Canceling :meth:`send` is discouraged. Instead, you should close the
connection with :meth:`close`. Indeed, there only two situations where
:meth:`send` yields control to the event loop:
1. The write buffer is full. If you don't want to wait until enough
data is sent, your only alternative is to close the connection.
:meth:`close` will likely time out then abort the TCP connection.
2. ``message`` is an asynchronous iterator. Stopping in the middle of
a fragmented message will cause a protocol error. Closing the
connection has the same effect.
:raises TypeError: for unsupported inputs
"""
await self.ensure_open()
# While sending a fragmented message, prevent sending other messages
# until all fragments are sent.
while self._fragmented_message_waiter is not None:
await asyncio.shield(self._fragmented_message_waiter)
# Unfragmented message -- this case must be handled first because
# strings and bytes-like objects are iterable.
if isinstance(message, (str, bytes, bytearray, memoryview)):
opcode, data = prepare_data(message)
await self.write_frame(True, opcode, data)
# Fragmented message -- regular iterator.
elif isinstance(message, Iterable):
# Work around https://github.com/python/mypy/issues/6227
message = cast(Iterable[Data], message)
iter_message = iter(message)
try:
message_chunk = next(iter_message)
except StopIteration:
return
opcode, data = prepare_data(message_chunk)
self._fragmented_message_waiter = asyncio.Future()
try:
# First fragment.
await self.write_frame(False, opcode, data)
# Other fragments.
for message_chunk in iter_message:
confirm_opcode, data = prepare_data(message_chunk)
if confirm_opcode != opcode:
raise TypeError("data contains inconsistent types")
await self.write_frame(False, OP_CONT, data)
# Final fragment.
await self.write_frame(True, OP_CONT, b"")
except Exception:
# We're half-way through a fragmented message and we can't
# complete it. This makes the connection unusable.
self.fail_connection(1011)
raise
finally:
self._fragmented_message_waiter.set_result(None)
self._fragmented_message_waiter = None
# Fragmented message -- asynchronous iterator
elif isinstance(message, AsyncIterable):
# aiter_message = aiter(message) without aiter
# https://github.com/python/mypy/issues/5738
aiter_message = type(message).__aiter__(message) # type: ignore
try:
# message_chunk = anext(aiter_message) without anext
# https://github.com/python/mypy/issues/5738
message_chunk = await type(aiter_message).__anext__( # type: ignore
aiter_message
)
except StopAsyncIteration:
return
opcode, data = prepare_data(message_chunk)
self._fragmented_message_waiter = asyncio.Future()
try:
# First fragment.
await self.write_frame(False, opcode, data)
# Other fragments.
# https://github.com/python/mypy/issues/5738
async for message_chunk in aiter_message: # type: ignore
confirm_opcode, data = prepare_data(message_chunk)
if confirm_opcode != opcode:
raise TypeError("data contains inconsistent types")
await self.write_frame(False, OP_CONT, data)
# Final fragment.
await self.write_frame(True, OP_CONT, b"")
except Exception:
# We're half-way through a fragmented message and we can't
# complete it. This makes the connection unusable.
self.fail_connection(1011)
raise
finally:
self._fragmented_message_waiter.set_result(None)
self._fragmented_message_waiter = None
else:
raise TypeError("data must be bytes, str, or iterable")
async def close(self, code: int = 1000, reason: str = "") -> None:
"""
Perform the closing handshake.
:meth:`close` waits for the other end to complete the handshake and
for the TCP connection to terminate. As a consequence, there's no need
to await :meth:`wait_closed`; :meth:`close` already does it.
:meth:`close` is idempotent: it doesn't do anything once the
connection is closed.
Wrapping :func:`close` in :func:`~asyncio.create_task` is safe, given
that errors during connection termination aren't particularly useful.
Canceling :meth:`close` is discouraged. If it takes too long, you can
set a shorter ``close_timeout``. If you don't want to wait, let the
Python process exit, then the OS will close the TCP connection.
:param code: WebSocket close code
:param reason: WebSocket close reason
"""
try:
await asyncio.wait_for(
self.write_close_frame(serialize_close(code, reason)),
self.close_timeout,
loop=self.loop if sys.version_info[:2] < (3, 8) else None,
)
except asyncio.TimeoutError:
# If the close frame cannot be sent because the send buffers
# are full, the closing handshake won't complete anyway.
# Fail the connection to shut down faster.
self.fail_connection()
# If no close frame is received within the timeout, wait_for() cancels
# the data transfer task and raises TimeoutError.
# If close() is called multiple times concurrently and one of these
# calls hits the timeout, the data transfer task will be cancelled.
# Other calls will receive a CancelledError here.
try:
# If close() is canceled during the wait, self.transfer_data_task
# is canceled before the timeout elapses.
await asyncio.wait_for(
self.transfer_data_task,
self.close_timeout,
loop=self.loop if sys.version_info[:2] < (3, 8) else None,
)
except (asyncio.TimeoutError, asyncio.CancelledError):
pass
# Wait for the close connection task to close the TCP connection.
await asyncio.shield(self.close_connection_task)
async def ping(self, data: Optional[Data] = None) -> Awaitable[None]:
"""
Send a ping.
Return a :class:`~asyncio.Future` which will be completed when the
corresponding pong is received and which you may ignore if you don't
want to wait.
A ping may serve as a keepalive or as a check that the remote endpoint
received all messages up to this point::
pong_waiter = await ws.ping()
await pong_waiter # only if you want to wait for the pong
By default, the ping contains four random bytes. This payload may be
overridden with the optional ``data`` argument which must be a string
(which will be encoded to UTF-8) or a bytes-like object.
Canceling :meth:`ping` is discouraged. If :meth:`ping` doesn't return
immediately, it means the write buffer is full. If you don't want to
wait, you should close the connection.
Canceling the :class:`~asyncio.Future` returned by :meth:`ping` has no
effect.
"""
await self.ensure_open()
if data is not None:
data = encode_data(data)
# Protect against duplicates if a payload is explicitly set.
if data in self.pings:
raise ValueError("already waiting for a pong with the same data")
# Generate a unique random payload otherwise.
while data is None or data in self.pings:
data = struct.pack("!I", random.getrandbits(32))
self.pings[data] = self.loop.create_future()
await self.write_frame(True, OP_PING, data)
return asyncio.shield(self.pings[data])
async def pong(self, data: Data = b"") -> None:
"""
Send a pong.
An unsolicited pong may serve as a unidirectional heartbeat.
The payload may be set with the optional ``data`` argument which must
be a string (which will be encoded to UTF-8) or a bytes-like object.
Canceling :meth:`pong` is discouraged for the same reason as
:meth:`ping`.
"""
await self.ensure_open()
data = encode_data(data)
await self.write_frame(True, OP_PONG, data)
# Private methods - no guarantees.
def connection_closed_exc(self) -> ConnectionClosed:
exception: ConnectionClosed
if self.close_code == 1000 or self.close_code == 1001:
exception = ConnectionClosedOK(self.close_code, self.close_reason)
else:
exception = ConnectionClosedError(self.close_code, self.close_reason)
# Chain to the exception that terminated data transfer, if any.
exception.__cause__ = self.transfer_data_exc
return exception
async def ensure_open(self) -> None:
"""
Check that the WebSocket connection is open.
Raise :exc:`~websockets.exceptions.ConnectionClosed` if it isn't.
"""
# Handle cases from most common to least common for performance.
if self.state is State.OPEN:
# If self.transfer_data_task exited without a closing handshake,
# self.close_connection_task may be closing the connection, going
# straight from OPEN to CLOSED.
if self.transfer_data_task.done():
await asyncio.shield(self.close_connection_task)
raise self.connection_closed_exc()
else:
return
if self.state is State.CLOSED:
raise self.connection_closed_exc()
if self.state is State.CLOSING:
# If we started the closing handshake, wait for its completion to
# get the proper close code and reason. self.close_connection_task
# will complete within 4 or 5 * close_timeout after close(). The
# CLOSING state also occurs when failing the connection. In that
# case self.close_connection_task will complete even faster.
await asyncio.shield(self.close_connection_task)
raise self.connection_closed_exc()
# Control may only reach this point in buggy third-party subclasses.
assert self.state is State.CONNECTING
raise InvalidState("WebSocket connection isn't established yet")
async def transfer_data(self) -> None:
"""
Read incoming messages and put them in a queue.
This coroutine runs in a task until the closing handshake is started.
"""
try:
while True:
message = await self.read_message()
# Exit the loop when receiving a close frame.
if message is None:
break
# Wait until there's room in the queue (if necessary).
if self.max_queue is not None:
while len(self.messages) >= self.max_queue:
self._put_message_waiter = self.loop.create_future()
try:
await asyncio.shield(self._put_message_waiter)
finally:
self._put_message_waiter = None
# Put the message in the queue.
self.messages.append(message)
# Notify recv().
if self._pop_message_waiter is not None:
self._pop_message_waiter.set_result(None)
self._pop_message_waiter = None
except asyncio.CancelledError as exc:
self.transfer_data_exc = exc
# If fail_connection() cancels this task, avoid logging the error
# twice and failing the connection again.
raise
except ProtocolError as exc:
self.transfer_data_exc = exc
self.fail_connection(1002)
except (ConnectionError, EOFError) as exc:
# Reading data with self.reader.readexactly may raise:
# - most subclasses of ConnectionError if the TCP connection
# breaks, is reset, or is aborted;
# - IncompleteReadError, a subclass of EOFError, if fewer
# bytes are available than requested.
self.transfer_data_exc = exc
self.fail_connection(1006)
except UnicodeDecodeError as exc:
self.transfer_data_exc = exc
self.fail_connection(1007)
except PayloadTooBig as exc:
self.transfer_data_exc = exc
self.fail_connection(1009)
except Exception as exc:
# This shouldn't happen often because exceptions expected under
# regular circumstances are handled above. If it does, consider
# catching and handling more exceptions.
logger.error("Error in data transfer", exc_info=True)
self.transfer_data_exc = exc
self.fail_connection(1011)
async def read_message(self) -> Optional[Data]:
"""
Read a single message from the connection.
Re-assemble data frames if the message is fragmented.
Return ``None`` when the closing handshake is started.
"""
frame = await self.read_data_frame(max_size=self.max_size)
# A close frame was received.
if frame is None:
return None
if frame.opcode == OP_TEXT:
text = True
elif frame.opcode == OP_BINARY:
text = False
else: # frame.opcode == OP_CONT
raise ProtocolError("unexpected opcode")
# Shortcut for the common case - no fragmentation
if frame.fin:
return frame.data.decode("utf-8") if text else frame.data
# 5.4. Fragmentation
chunks: List[Data] = []
max_size = self.max_size
if text:
decoder_factory = codecs.getincrementaldecoder("utf-8")
decoder = decoder_factory(errors="strict")
if max_size is None:
def append(frame: Frame) -> None:
nonlocal chunks
chunks.append(decoder.decode(frame.data, frame.fin))
else:
def append(frame: Frame) -> None:
nonlocal chunks, max_size
chunks.append(decoder.decode(frame.data, frame.fin))
assert isinstance(max_size, int)
max_size -= len(frame.data)
else:
if max_size is None:
def append(frame: Frame) -> None:
nonlocal chunks
chunks.append(frame.data)
else:
def append(frame: Frame) -> None:
nonlocal chunks, max_size
chunks.append(frame.data)
assert isinstance(max_size, int)
max_size -= len(frame.data)
append(frame)
while not frame.fin:
frame = await self.read_data_frame(max_size=max_size)
if frame is None:
raise ProtocolError("incomplete fragmented message")
if frame.opcode != OP_CONT:
raise ProtocolError("unexpected opcode")
append(frame)
# mypy cannot figure out that chunks have the proper type.
return ("" if text else b"").join(chunks) # type: ignore
async def read_data_frame(self, max_size: Optional[int]) -> Optional[Frame]:
"""
Read a single data frame from the connection.
Process control frames received before the next data frame.
Return ``None`` if a close frame is encountered before any data frame.
"""
# 6.2. Receiving Data
while True:
frame = await self.read_frame(max_size)
# 5.5. Control Frames
if frame.opcode == OP_CLOSE:
# 7.1.5. The WebSocket Connection Close Code
# 7.1.6. The WebSocket Connection Close Reason
self.close_code, self.close_reason = parse_close(frame.data)
try:
# Echo the original data instead of re-serializing it with
# serialize_close() because that fails when the close frame
# is empty and parse_close() synthetizes a 1005 close code.
await self.write_close_frame(frame.data)
except ConnectionClosed:
# It doesn't really matter if the connection was closed
# before we could send back a close frame.
pass
return None
elif frame.opcode == OP_PING:
# Answer pings.
ping_hex = frame.data.hex() or "[empty]"
logger.debug(
"%s - received ping, sending pong: %s", self.side, ping_hex
)
await self.pong(frame.data)
elif frame.opcode == OP_PONG:
# Acknowledge pings on solicited pongs.
if frame.data in self.pings:
logger.debug(
"%s - received solicited pong: %s",
self.side,
frame.data.hex() or "[empty]",
)
# Acknowledge all pings up to the one matching this pong.
ping_id = None
ping_ids = []
for ping_id, ping in self.pings.items():
ping_ids.append(ping_id)
if not ping.done():
ping.set_result(None)
if ping_id == frame.data:
break
else: # pragma: no cover
assert False, "ping_id is in self.pings"
# Remove acknowledged pings from self.pings.
for ping_id in ping_ids:
del self.pings[ping_id]
ping_ids = ping_ids[:-1]
if ping_ids:
pings_hex = ", ".join(
ping_id.hex() or "[empty]" for ping_id in ping_ids
)
plural = "s" if len(ping_ids) > 1 else ""
logger.debug(
"%s - acknowledged previous ping%s: %s",
self.side,
plural,
pings_hex,
)
else:
logger.debug(
"%s - received unsolicited pong: %s",
self.side,
frame.data.hex() or "[empty]",
)
# 5.6. Data Frames
else:
return frame
async def read_frame(self, max_size: Optional[int]) -> Frame:
"""
Read a single frame from the connection.
"""
frame = await Frame.read(
self.reader.readexactly,
mask=not self.is_client,
max_size=max_size,
extensions=self.extensions,
)
logger.debug("%s < %r", self.side, frame)
return frame
async def write_frame(
self, fin: bool, opcode: int, data: bytes, *, _expected_state: int = State.OPEN
) -> None:
# Defensive assertion for protocol compliance.
if self.state is not _expected_state: # pragma: no cover
raise InvalidState(
f"Cannot write to a WebSocket in the {self.state.name} state"
)
frame = Frame(fin, opcode, data)
logger.debug("%s > %r", self.side, frame)
frame.write(
self.transport.write, mask=self.is_client, extensions=self.extensions
)
try:
# drain() cannot be called concurrently by multiple coroutines:
# http://bugs.python.org/issue29930. Remove this lock when no
# version of Python where this bugs exists is supported anymore.
async with self._drain_lock:
# Handle flow control automatically.
await self._drain()
except ConnectionError:
# Terminate the connection if the socket died.
self.fail_connection()
# Wait until the connection is closed to raise ConnectionClosed
# with the correct code and reason.
await self.ensure_open()
async def write_close_frame(self, data: bytes = b"") -> None:
"""
Write a close frame if and only if the connection state is OPEN.
This dedicated coroutine must be used for writing close frames to
ensure that at most one close frame is sent on a given connection.
"""
# Test and set the connection state before sending the close frame to
# avoid sending two frames in case of concurrent calls.
if self.state is State.OPEN:
# 7.1.3. The WebSocket Closing Handshake is Started
self.state = State.CLOSING
logger.debug("%s - state = CLOSING", self.side)
# 7.1.2. Start the WebSocket Closing Handshake
await self.write_frame(True, OP_CLOSE, data, _expected_state=State.CLOSING)
async def keepalive_ping(self) -> None:
"""
Send a Ping frame and wait for a Pong frame at regular intervals.
This coroutine exits when the connection terminates and one of the
following happens:
- :meth:`ping` raises :exc:`ConnectionClosed`, or
- :meth:`close_connection` cancels :attr:`keepalive_ping_task`.
"""
if self.ping_interval is None:
return
try:
while True:
await asyncio.sleep(
self.ping_interval,
loop=self.loop if sys.version_info[:2] < (3, 8) else None,
)
# ping() raises CancelledError if the connection is closed,
# when close_connection() cancels self.keepalive_ping_task.
# ping() raises ConnectionClosed if the connection is lost,
# when connection_lost() calls abort_pings().
ping_waiter = await self.ping()
if self.ping_timeout is not None:
try:
await asyncio.wait_for(
ping_waiter,
self.ping_timeout,
loop=self.loop if sys.version_info[:2] < (3, 8) else None,
)
except asyncio.TimeoutError:
logger.debug("%s ! timed out waiting for pong", self.side)
self.fail_connection(1011)
break
except asyncio.CancelledError:
raise
except ConnectionClosed:
pass
except Exception:
logger.warning("Unexpected exception in keepalive ping task", exc_info=True)
async def close_connection(self) -> None:
"""
7.1.1. Close the WebSocket Connection
When the opening handshake succeeds, :meth:`connection_open` starts
this coroutine in a task. It waits for the data transfer phase to
complete then it closes the TCP connection cleanly.
When the opening handshake fails, :meth:`fail_connection` does the
same. There's no data transfer phase in that case.
"""
try:
# Wait for the data transfer phase to complete.
if hasattr(self, "transfer_data_task"):
try:
await self.transfer_data_task
except asyncio.CancelledError:
pass
# Cancel the keepalive ping task.
if hasattr(self, "keepalive_ping_task"):
self.keepalive_ping_task.cancel()
# A client should wait for a TCP close from the server.
if self.is_client and hasattr(self, "transfer_data_task"):
if await self.wait_for_connection_lost():
return
logger.debug("%s ! timed out waiting for TCP close", self.side)
# Half-close the TCP connection if possible (when there's no TLS).
if self.transport.can_write_eof():
logger.debug("%s x half-closing TCP connection", self.side)
self.transport.write_eof()
if await self.wait_for_connection_lost():
return
logger.debug("%s ! timed out waiting for TCP close", self.side)
finally:
# The try/finally ensures that the transport never remains open,
# even if this coroutine is canceled (for example).
# If connection_lost() was called, the TCP connection is closed.
# However, if TLS is enabled, the transport still needs closing.
# Else asyncio complains: ResourceWarning: unclosed transport.
if self.connection_lost_waiter.done() and self.transport.is_closing():
return
# Close the TCP connection. Buffers are flushed asynchronously.
logger.debug("%s x closing TCP connection", self.side)
self.transport.close()
if await self.wait_for_connection_lost():
return
logger.debug("%s ! timed out waiting for TCP close", self.side)
# Abort the TCP connection. Buffers are discarded.
logger.debug("%s x aborting TCP connection", self.side)
self.transport.abort()
# connection_lost() is called quickly after aborting.
await self.wait_for_connection_lost()
async def wait_for_connection_lost(self) -> bool:
"""
Wait until the TCP connection is closed or ``self.close_timeout`` elapses.
Return ``True`` if the connection is closed and ``False`` otherwise.
"""
if not self.connection_lost_waiter.done():
try:
await asyncio.wait_for(
asyncio.shield(self.connection_lost_waiter),
self.close_timeout,
loop=self.loop if sys.version_info[:2] < (3, 8) else None,
)
except asyncio.TimeoutError:
pass
# Re-check self.connection_lost_waiter.done() synchronously because
# connection_lost() could run between the moment the timeout occurs
# and the moment this coroutine resumes running.
return self.connection_lost_waiter.done()
def fail_connection(self, code: int = 1006, reason: str = "") -> None:
"""
7.1.7. Fail the WebSocket Connection
This requires:
1. Stopping all processing of incoming data, which means cancelling
:attr:`transfer_data_task`. The close code will be 1006 unless a
close frame was received earlier.
2. Sending a close frame with an appropriate code if the opening
handshake succeeded and the other side is likely to process it.
3. Closing the connection. :meth:`close_connection` takes care of
this once :attr:`transfer_data_task` exits after being canceled.
(The specification describes these steps in the opposite order.)
"""
logger.debug(
"%s ! failing %s WebSocket connection with code %d",
self.side,
self.state.name,
code,
)
# Cancel transfer_data_task if the opening handshake succeeded.
# cancel() is idempotent and ignored if the task is done already.
if hasattr(self, "transfer_data_task"):
self.transfer_data_task.cancel()
# Send a close frame when the state is OPEN (a close frame was already
# sent if it's CLOSING), except when failing the connection because of
# an error reading from or writing to the network.
# Don't send a close frame if the connection is broken.
if code != 1006 and self.state is State.OPEN:
frame_data = serialize_close(code, reason)
# Write the close frame without draining the write buffer.
# Keeping fail_connection() synchronous guarantees it can't
# get stuck and simplifies the implementation of the callers.
# Not drainig the write buffer is acceptable in this context.
# This duplicates a few lines of code from write_close_frame()
# and write_frame().
self.state = State.CLOSING
logger.debug("%s - state = CLOSING", self.side)
frame = Frame(True, OP_CLOSE, frame_data)
logger.debug("%s > %r", self.side, frame)
frame.write(
self.transport.write, mask=self.is_client, extensions=self.extensions
)
# Start close_connection_task if the opening handshake didn't succeed.
if not hasattr(self, "close_connection_task"):
self.close_connection_task = self.loop.create_task(self.close_connection())
def abort_pings(self) -> None:
"""
Raise ConnectionClosed in pending keepalive pings.
They'll never receive a pong once the connection is closed.
"""
assert self.state is State.CLOSED
exc = self.connection_closed_exc()
for ping in self.pings.values():
ping.set_exception(exc)
# If the exception is never retrieved, it will be logged when ping
# is garbage-collected. This is confusing for users.
# Given that ping is done (with an exception), canceling it does
# nothing, but it prevents logging the exception.
ping.cancel()
if self.pings:
pings_hex = ", ".join(ping_id.hex() or "[empty]" for ping_id in self.pings)
plural = "s" if len(self.pings) > 1 else ""
logger.debug(
"%s - aborted pending ping%s: %s", self.side, plural, pings_hex
)
# asyncio.Protocol methods
def connection_made(self, transport: asyncio.BaseTransport) -> None:
"""
Configure write buffer limits.
The high-water limit is defined by ``self.write_limit``.
The low-water limit currently defaults to ``self.write_limit // 4`` in
:meth:`~asyncio.WriteTransport.set_write_buffer_limits`, which should
be all right for reasonable use cases of this library.
This is the earliest point where we can get hold of the transport,
which means it's the best point for configuring it.
"""
logger.debug("%s - event = connection_made(%s)", self.side, transport)
transport = cast(asyncio.Transport, transport)
transport.set_write_buffer_limits(self.write_limit)
self.transport = transport
# Copied from asyncio.StreamReaderProtocol
self.reader.set_transport(transport)
def connection_lost(self, exc: Optional[Exception]) -> None:
"""
7.1.4. The WebSocket Connection is Closed.
"""
logger.debug("%s - event = connection_lost(%s)", self.side, exc)
self.state = State.CLOSED
logger.debug("%s - state = CLOSED", self.side)
if not hasattr(self, "close_code"):
self.close_code = 1006
if not hasattr(self, "close_reason"):
self.close_reason = ""
logger.debug(
"%s x code = %d, reason = %s",
self.side,
self.close_code,
self.close_reason or "[no reason]",
)
self.abort_pings()
# If self.connection_lost_waiter isn't pending, that's a bug, because:
# - it's set only here in connection_lost() which is called only once;
# - it must never be canceled.
self.connection_lost_waiter.set_result(None)
if True: # pragma: no cover
# Copied from asyncio.StreamReaderProtocol
if self.reader is not None:
if exc is None:
self.reader.feed_eof()
else:
self.reader.set_exception(exc)
# Copied from asyncio.FlowControlMixin
# Wake up the writer if currently paused.
if not self._paused:
return
waiter = self._drain_waiter
if waiter is None:
return
self._drain_waiter = None
if waiter.done():
return
if exc is None:
waiter.set_result(None)
else:
waiter.set_exception(exc)
def pause_writing(self) -> None: # pragma: no cover
assert not self._paused
self._paused = True
def resume_writing(self) -> None: # pragma: no cover
assert self._paused
self._paused = False
waiter = self._drain_waiter
if waiter is not None:
self._drain_waiter = None
if not waiter.done():
waiter.set_result(None)
def data_received(self, data: bytes) -> None:
logger.debug("%s - event = data_received(<%d bytes>)", self.side, len(data))
self.reader.feed_data(data)
def eof_received(self) -> None:
"""
Close the transport after receiving EOF.
The WebSocket protocol has its own closing handshake: endpoints close
the TCP or TLS connection after sending and receiving a close frame.
As a consequence, they never need to write after receiving EOF, so
there's no reason to keep the transport open by returning ``True``.
Besides, that doesn't work on TLS connections.
"""
logger.debug("%s - event = eof_received()", self.side)
self.reader.feed_eof()
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 011453 x ustar 00 0000000 0000000 22 mtime=1561574292.0
websockets-8.1/src/websockets/py.typed 0000644 0000765 0000024 00000000000 00000000000 020104 0 ustar 00myk staff 0000000 0000000 ././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 011453 x ustar 00 0000000 0000000 22 mtime=1572595517.0
websockets-8.1/src/websockets/server.py 0000644 0000765 0000024 00000112452 00000000000 020304 0 ustar 00myk staff 0000000 0000000 """
:mod:`websockets.server` defines the WebSocket server APIs.
"""
import asyncio
import collections.abc
import email.utils
import functools
import http
import logging
import socket
import sys
import warnings
from types import TracebackType
from typing import (
Any,
Awaitable,
Callable,
Generator,
List,
Optional,
Sequence,
Set,
Tuple,
Type,
Union,
cast,
)
from .exceptions import (
AbortHandshake,
InvalidHandshake,
InvalidHeader,
InvalidMessage,
InvalidOrigin,
InvalidUpgrade,
NegotiationError,
)
from .extensions.base import Extension, ServerExtensionFactory
from .extensions.permessage_deflate import ServerPerMessageDeflateFactory
from .handshake import build_response, check_request
from .headers import build_extension, parse_extension, parse_subprotocol
from .http import USER_AGENT, Headers, HeadersLike, MultipleValuesError, read_request
from .protocol import WebSocketCommonProtocol
from .typing import ExtensionHeader, Origin, Subprotocol
__all__ = ["serve", "unix_serve", "WebSocketServerProtocol", "WebSocketServer"]
logger = logging.getLogger(__name__)
HeadersLikeOrCallable = Union[HeadersLike, Callable[[str, Headers], HeadersLike]]
HTTPResponse = Tuple[http.HTTPStatus, HeadersLike, bytes]
class WebSocketServerProtocol(WebSocketCommonProtocol):
"""
:class:`~asyncio.Protocol` subclass implementing a WebSocket server.
This class inherits most of its methods from
:class:`~websockets.protocol.WebSocketCommonProtocol`.
For the sake of simplicity, it doesn't rely on a full HTTP implementation.
Its support for HTTP responses is very limited.
"""
is_client = False
side = "server"
def __init__(
self,
ws_handler: Callable[["WebSocketServerProtocol", str], Awaitable[Any]],
ws_server: "WebSocketServer",
*,
origins: Optional[Sequence[Optional[Origin]]] = None,
extensions: Optional[Sequence[ServerExtensionFactory]] = None,
subprotocols: Optional[Sequence[Subprotocol]] = None,
extra_headers: Optional[HeadersLikeOrCallable] = None,
process_request: Optional[
Callable[[str, Headers], Awaitable[Optional[HTTPResponse]]]
] = None,
select_subprotocol: Optional[
Callable[[Sequence[Subprotocol], Sequence[Subprotocol]], Subprotocol]
] = None,
**kwargs: Any,
) -> None:
# For backwards compatibility with 6.0 or earlier.
if origins is not None and "" in origins:
warnings.warn("use None instead of '' in origins", DeprecationWarning)
origins = [None if origin == "" else origin for origin in origins]
self.ws_handler = ws_handler
self.ws_server = ws_server
self.origins = origins
self.available_extensions = extensions
self.available_subprotocols = subprotocols
self.extra_headers = extra_headers
self._process_request = process_request
self._select_subprotocol = select_subprotocol
super().__init__(**kwargs)
def connection_made(self, transport: asyncio.BaseTransport) -> None:
"""
Register connection and initialize a task to handle it.
"""
super().connection_made(transport)
# Register the connection with the server before creating the handler
# task. Registering at the beginning of the handler coroutine would
# create a race condition between the creation of the task, which
# schedules its execution, and the moment the handler starts running.
self.ws_server.register(self)
self.handler_task = self.loop.create_task(self.handler())
async def handler(self) -> None:
"""
Handle the lifecycle of a WebSocket connection.
Since this method doesn't have a caller able to handle exceptions, it
attemps to log relevant ones and guarantees that the TCP connection is
closed before exiting.
"""
try:
try:
path = await self.handshake(
origins=self.origins,
available_extensions=self.available_extensions,
available_subprotocols=self.available_subprotocols,
extra_headers=self.extra_headers,
)
except ConnectionError:
logger.debug("Connection error in opening handshake", exc_info=True)
raise
except Exception as exc:
if isinstance(exc, AbortHandshake):
status, headers, body = exc.status, exc.headers, exc.body
elif isinstance(exc, InvalidOrigin):
logger.debug("Invalid origin", exc_info=True)
status, headers, body = (
http.HTTPStatus.FORBIDDEN,
Headers(),
f"Failed to open a WebSocket connection: {exc}.\n".encode(),
)
elif isinstance(exc, InvalidUpgrade):
logger.debug("Invalid upgrade", exc_info=True)
status, headers, body = (
http.HTTPStatus.UPGRADE_REQUIRED,
Headers([("Upgrade", "websocket")]),
(
f"Failed to open a WebSocket connection: {exc}.\n"
f"\n"
f"You cannot access a WebSocket server directly "
f"with a browser. You need a WebSocket client.\n"
).encode(),
)
elif isinstance(exc, InvalidHandshake):
logger.debug("Invalid handshake", exc_info=True)
status, headers, body = (
http.HTTPStatus.BAD_REQUEST,
Headers(),
f"Failed to open a WebSocket connection: {exc}.\n".encode(),
)
else:
logger.warning("Error in opening handshake", exc_info=True)
status, headers, body = (
http.HTTPStatus.INTERNAL_SERVER_ERROR,
Headers(),
(
b"Failed to open a WebSocket connection.\n"
b"See server log for more information.\n"
),
)
headers.setdefault("Date", email.utils.formatdate(usegmt=True))
headers.setdefault("Server", USER_AGENT)
headers.setdefault("Content-Length", str(len(body)))
headers.setdefault("Content-Type", "text/plain")
headers.setdefault("Connection", "close")
self.write_http_response(status, headers, body)
self.fail_connection()
await self.wait_closed()
return
try:
await self.ws_handler(self, path)
except Exception:
logger.error("Error in connection handler", exc_info=True)
if not self.closed:
self.fail_connection(1011)
raise
try:
await self.close()
except ConnectionError:
logger.debug("Connection error in closing handshake", exc_info=True)
raise
except Exception:
logger.warning("Error in closing handshake", exc_info=True)
raise
except Exception:
# Last-ditch attempt to avoid leaking connections on errors.
try:
self.transport.close()
except Exception: # pragma: no cover
pass
finally:
# Unregister the connection with the server when the handler task
# terminates. Registration is tied to the lifecycle of the handler
# task because the server waits for tasks attached to registered
# connections before terminating.
self.ws_server.unregister(self)
async def read_http_request(self) -> Tuple[str, Headers]:
"""
Read request line and headers from the HTTP request.
If the request contains a body, it may be read from ``self.reader``
after this coroutine returns.
:raises ~websockets.exceptions.InvalidMessage: if the HTTP message is
malformed or isn't an HTTP/1.1 GET request
"""
try:
path, headers = await read_request(self.reader)
except Exception as exc:
raise InvalidMessage("did not receive a valid HTTP request") from exc
logger.debug("%s < GET %s HTTP/1.1", self.side, path)
logger.debug("%s < %r", self.side, headers)
self.path = path
self.request_headers = headers
return path, headers
def write_http_response(
self, status: http.HTTPStatus, headers: Headers, body: Optional[bytes] = None
) -> None:
"""
Write status line and headers to the HTTP response.
This coroutine is also able to write a response body.
"""
self.response_headers = headers
logger.debug("%s > HTTP/1.1 %d %s", self.side, status.value, status.phrase)
logger.debug("%s > %r", self.side, headers)
# Since the status line and headers only contain ASCII characters,
# we can keep this simple.
response = f"HTTP/1.1 {status.value} {status.phrase}\r\n"
response += str(headers)
self.transport.write(response.encode())
if body is not None:
logger.debug("%s > body (%d bytes)", self.side, len(body))
self.transport.write(body)
async def process_request(
self, path: str, request_headers: Headers
) -> Optional[HTTPResponse]:
"""
Intercept the HTTP request and return an HTTP response if appropriate.
If ``process_request`` returns ``None``, the WebSocket handshake
continues. If it returns 3-uple containing a status code, response
headers and a response body, that HTTP response is sent and the
connection is closed. In that case:
* The HTTP status must be a :class:`~http.HTTPStatus`.
* HTTP headers must be a :class:`~websockets.http.Headers` instance, a
:class:`~collections.abc.Mapping`, or an iterable of ``(name,
value)`` pairs.
* The HTTP response body must be :class:`bytes`. It may be empty.
This coroutine may be overridden in a :class:`WebSocketServerProtocol`
subclass, for example:
* to return a HTTP 200 OK response on a given path; then a load
balancer can use this path for a health check;
* to authenticate the request and return a HTTP 401 Unauthorized or a
HTTP 403 Forbidden when authentication fails.
Instead of subclassing, it is possible to override this method by
passing a ``process_request`` argument to the :func:`serve` function
or the :class:`WebSocketServerProtocol` constructor. This is
equivalent, except ``process_request`` won't have access to the
protocol instance, so it can't store information for later use.
``process_request`` is expected to complete quickly. If it may run for
a long time, then it should await :meth:`wait_closed` and exit if
:meth:`wait_closed` completes, or else it could prevent the server
from shutting down.
:param path: request path, including optional query string
:param request_headers: request headers
"""
if self._process_request is not None:
response = self._process_request(path, request_headers)
if isinstance(response, Awaitable):
return await response
else:
# For backwards compatibility with 7.0.
warnings.warn(
"declare process_request as a coroutine", DeprecationWarning
)
return response # type: ignore
return None
@staticmethod
def process_origin(
headers: Headers, origins: Optional[Sequence[Optional[Origin]]] = None
) -> Optional[Origin]:
"""
Handle the Origin HTTP request header.
:param headers: request headers
:param origins: optional list of acceptable origins
:raises ~websockets.exceptions.InvalidOrigin: if the origin isn't
acceptable
"""
# "The user agent MUST NOT include more than one Origin header field"
# per https://tools.ietf.org/html/rfc6454#section-7.3.
try:
origin = cast(Origin, headers.get("Origin"))
except MultipleValuesError:
raise InvalidHeader("Origin", "more than one Origin header found")
if origins is not None:
if origin not in origins:
raise InvalidOrigin(origin)
return origin
@staticmethod
def process_extensions(
headers: Headers,
available_extensions: Optional[Sequence[ServerExtensionFactory]],
) -> Tuple[Optional[str], List[Extension]]:
"""
Handle the Sec-WebSocket-Extensions HTTP request header.
Accept or reject each extension proposed in the client request.
Negotiate parameters for accepted extensions.
Return the Sec-WebSocket-Extensions HTTP response header and the list
of accepted extensions.
:rfc:`6455` leaves the rules up to the specification of each
:extension.
To provide this level of flexibility, for each extension proposed by
the client, we check for a match with each extension available in the
server configuration. If no match is found, the extension is ignored.
If several variants of the same extension are proposed by the client,
it may be accepted severel times, which won't make sense in general.
Extensions must implement their own requirements. For this purpose,
the list of previously accepted extensions is provided.
This process doesn't allow the server to reorder extensions. It can
only select a subset of the extensions proposed by the client.
Other requirements, for example related to mandatory extensions or the
order of extensions, may be implemented by overriding this method.
:param headers: request headers
:param extensions: optional list of supported extensions
:raises ~websockets.exceptions.InvalidHandshake: to abort the
handshake with an HTTP 400 error code
"""
response_header_value: Optional[str] = None
extension_headers: List[ExtensionHeader] = []
accepted_extensions: List[Extension] = []
header_values = headers.get_all("Sec-WebSocket-Extensions")
if header_values and available_extensions:
parsed_header_values: List[ExtensionHeader] = sum(
[parse_extension(header_value) for header_value in header_values], []
)
for name, request_params in parsed_header_values:
for ext_factory in available_extensions:
# Skip non-matching extensions based on their name.
if ext_factory.name != name:
continue
# Skip non-matching extensions based on their params.
try:
response_params, extension = ext_factory.process_request_params(
request_params, accepted_extensions
)
except NegotiationError:
continue
# Add matching extension to the final list.
extension_headers.append((name, response_params))
accepted_extensions.append(extension)
# Break out of the loop once we have a match.
break
# If we didn't break from the loop, no extension in our list
# matched what the client sent. The extension is declined.
# Serialize extension header.
if extension_headers:
response_header_value = build_extension(extension_headers)
return response_header_value, accepted_extensions
# Not @staticmethod because it calls self.select_subprotocol()
def process_subprotocol(
self, headers: Headers, available_subprotocols: Optional[Sequence[Subprotocol]]
) -> Optional[Subprotocol]:
"""
Handle the Sec-WebSocket-Protocol HTTP request header.
Return Sec-WebSocket-Protocol HTTP response header, which is the same
as the selected subprotocol.
:param headers: request headers
:param available_subprotocols: optional list of supported subprotocols
:raises ~websockets.exceptions.InvalidHandshake: to abort the
handshake with an HTTP 400 error code
"""
subprotocol: Optional[Subprotocol] = None
header_values = headers.get_all("Sec-WebSocket-Protocol")
if header_values and available_subprotocols:
parsed_header_values: List[Subprotocol] = sum(
[parse_subprotocol(header_value) for header_value in header_values], []
)
subprotocol = self.select_subprotocol(
parsed_header_values, available_subprotocols
)
return subprotocol
def select_subprotocol(
self,
client_subprotocols: Sequence[Subprotocol],
server_subprotocols: Sequence[Subprotocol],
) -> Optional[Subprotocol]:
"""
Pick a subprotocol among those offered by the client.
If several subprotocols are supported by the client and the server,
the default implementation selects the preferred subprotocols by
giving equal value to the priorities of the client and the server.
If no subprotocol is supported by the client and the server, it
proceeds without a subprotocol.
This is unlikely to be the most useful implementation in practice, as
many servers providing a subprotocol will require that the client uses
that subprotocol. Such rules can be implemented in a subclass.
Instead of subclassing, it is possible to override this method by
passing a ``select_subprotocol`` argument to the :func:`serve`
function or the :class:`WebSocketServerProtocol` constructor
:param client_subprotocols: list of subprotocols offered by the client
:param server_subprotocols: list of subprotocols available on the server
"""
if self._select_subprotocol is not None:
return self._select_subprotocol(client_subprotocols, server_subprotocols)
subprotocols = set(client_subprotocols) & set(server_subprotocols)
if not subprotocols:
return None
priority = lambda p: (
client_subprotocols.index(p) + server_subprotocols.index(p)
)
return sorted(subprotocols, key=priority)[0]
async def handshake(
self,
origins: Optional[Sequence[Optional[Origin]]] = None,
available_extensions: Optional[Sequence[ServerExtensionFactory]] = None,
available_subprotocols: Optional[Sequence[Subprotocol]] = None,
extra_headers: Optional[HeadersLikeOrCallable] = None,
) -> str:
"""
Perform the server side of the opening handshake.
Return the path of the URI of the request.
:param origins: list of acceptable values of the Origin HTTP header;
include ``None`` if the lack of an origin is acceptable
:param available_extensions: list of supported extensions in the order
in which they should be used
:param available_subprotocols: list of supported subprotocols in order
of decreasing preference
:param extra_headers: sets additional HTTP response headers when the
handshake succeeds; it can be a :class:`~websockets.http.Headers`
instance, a :class:`~collections.abc.Mapping`, an iterable of
``(name, value)`` pairs, or a callable taking the request path and
headers in arguments and returning one of the above.
:raises ~websockets.exceptions.InvalidHandshake: if the handshake
fails
"""
path, request_headers = await self.read_http_request()
# Hook for customizing request handling, for example checking
# authentication or treating some paths as plain HTTP endpoints.
early_response_awaitable = self.process_request(path, request_headers)
if isinstance(early_response_awaitable, Awaitable):
early_response = await early_response_awaitable
else:
# For backwards compatibility with 7.0.
warnings.warn("declare process_request as a coroutine", DeprecationWarning)
early_response = early_response_awaitable # type: ignore
# Change the response to a 503 error if the server is shutting down.
if not self.ws_server.is_serving():
early_response = (
http.HTTPStatus.SERVICE_UNAVAILABLE,
[],
b"Server is shutting down.\n",
)
if early_response is not None:
raise AbortHandshake(*early_response)
key = check_request(request_headers)
self.origin = self.process_origin(request_headers, origins)
extensions_header, self.extensions = self.process_extensions(
request_headers, available_extensions
)
protocol_header = self.subprotocol = self.process_subprotocol(
request_headers, available_subprotocols
)
response_headers = Headers()
build_response(response_headers, key)
if extensions_header is not None:
response_headers["Sec-WebSocket-Extensions"] = extensions_header
if protocol_header is not None:
response_headers["Sec-WebSocket-Protocol"] = protocol_header
if callable(extra_headers):
extra_headers = extra_headers(path, self.request_headers)
if extra_headers is not None:
if isinstance(extra_headers, Headers):
extra_headers = extra_headers.raw_items()
elif isinstance(extra_headers, collections.abc.Mapping):
extra_headers = extra_headers.items()
for name, value in extra_headers:
response_headers[name] = value
response_headers.setdefault("Date", email.utils.formatdate(usegmt=True))
response_headers.setdefault("Server", USER_AGENT)
self.write_http_response(http.HTTPStatus.SWITCHING_PROTOCOLS, response_headers)
self.connection_open()
return path
class WebSocketServer:
"""
WebSocket server returned by :func:`~websockets.server.serve`.
This class provides the same interface as
:class:`~asyncio.AbstractServer`, namely the
:meth:`~asyncio.AbstractServer.close` and
:meth:`~asyncio.AbstractServer.wait_closed` methods.
It keeps track of WebSocket connections in order to close them properly
when shutting down.
Instances of this class store a reference to the :class:`~asyncio.Server`
object returned by :meth:`~asyncio.loop.create_server` rather than inherit
from :class:`~asyncio.Server` in part because
:meth:`~asyncio.loop.create_server` doesn't support passing a custom
:class:`~asyncio.Server` class.
"""
def __init__(self, loop: asyncio.AbstractEventLoop) -> None:
# Store a reference to loop to avoid relying on self.server._loop.
self.loop = loop
# Keep track of active connections.
self.websockets: Set[WebSocketServerProtocol] = set()
# Task responsible for closing the server and terminating connections.
self.close_task: Optional[asyncio.Task[None]] = None
# Completed when the server is closed and connections are terminated.
self.closed_waiter: asyncio.Future[None] = loop.create_future()
def wrap(self, server: asyncio.AbstractServer) -> None:
"""
Attach to a given :class:`~asyncio.Server`.
Since :meth:`~asyncio.loop.create_server` doesn't support injecting a
custom ``Server`` class, the easiest solution that doesn't rely on
private :mod:`asyncio` APIs is to:
- instantiate a :class:`WebSocketServer`
- give the protocol factory a reference to that instance
- call :meth:`~asyncio.loop.create_server` with the factory
- attach the resulting :class:`~asyncio.Server` with this method
"""
self.server = server
def register(self, protocol: WebSocketServerProtocol) -> None:
"""
Register a connection with this server.
"""
self.websockets.add(protocol)
def unregister(self, protocol: WebSocketServerProtocol) -> None:
"""
Unregister a connection with this server.
"""
self.websockets.remove(protocol)
def is_serving(self) -> bool:
"""
Tell whether the server is accepting new connections or shutting down.
"""
try:
# Python ≥ 3.7
return self.server.is_serving()
except AttributeError: # pragma: no cover
# Python < 3.7
return self.server.sockets is not None
def close(self) -> None:
"""
Close the server.
This method:
* closes the underlying :class:`~asyncio.Server`;
* rejects new WebSocket connections with an HTTP 503 (service
unavailable) error; this happens when the server accepted the TCP
connection but didn't complete the WebSocket opening handshake prior
to closing;
* closes open WebSocket connections with close code 1001 (going away).
:meth:`close` is idempotent.
"""
if self.close_task is None:
self.close_task = self.loop.create_task(self._close())
async def _close(self) -> None:
"""
Implementation of :meth:`close`.
This calls :meth:`~asyncio.Server.close` on the underlying
:class:`~asyncio.Server` object to stop accepting new connections and
then closes open connections with close code 1001.
"""
# Stop accepting new connections.
self.server.close()
# Wait until self.server.close() completes.
await self.server.wait_closed()
# Wait until all accepted connections reach connection_made() and call
# register(). See https://bugs.python.org/issue34852 for details.
await asyncio.sleep(
0, loop=self.loop if sys.version_info[:2] < (3, 8) else None
)
# Close OPEN connections with status code 1001. Since the server was
# closed, handshake() closes OPENING conections with a HTTP 503 error.
# Wait until all connections are closed.
# asyncio.wait doesn't accept an empty first argument
if self.websockets:
await asyncio.wait(
[websocket.close(1001) for websocket in self.websockets],
loop=self.loop if sys.version_info[:2] < (3, 8) else None,
)
# Wait until all connection handlers are complete.
# asyncio.wait doesn't accept an empty first argument.
if self.websockets:
await asyncio.wait(
[websocket.handler_task for websocket in self.websockets],
loop=self.loop if sys.version_info[:2] < (3, 8) else None,
)
# Tell wait_closed() to return.
self.closed_waiter.set_result(None)
async def wait_closed(self) -> None:
"""
Wait until the server is closed.
When :meth:`wait_closed` returns, all TCP connections are closed and
all connection handlers have returned.
"""
await asyncio.shield(self.closed_waiter)
@property
def sockets(self) -> Optional[List[socket.socket]]:
"""
List of :class:`~socket.socket` objects the server is listening to.
``None`` if the server is closed.
"""
return self.server.sockets
class Serve:
"""
Create, start, and return a WebSocket server on ``host`` and ``port``.
Whenever a client connects, the server accepts the connection, creates a
:class:`WebSocketServerProtocol`, performs the opening handshake, and
delegates to the connection handler defined by ``ws_handler``. Once the
handler completes, either normally or with an exception, the server
performs the closing handshake and closes the connection.
Awaiting :func:`serve` yields a :class:`WebSocketServer`. This instance
provides :meth:`~websockets.server.WebSocketServer.close` and
:meth:`~websockets.server.WebSocketServer.wait_closed` methods for
terminating the server and cleaning up its resources.
When a server is closed with :meth:`~WebSocketServer.close`, it closes all
connections with close code 1001 (going away). Connections handlers, which
are running the ``ws_handler`` coroutine, will receive a
:exc:`~websockets.exceptions.ConnectionClosedOK` exception on their
current or next interaction with the WebSocket connection.
:func:`serve` can also be used as an asynchronous context manager. In
this case, the server is shut down when exiting the context.
:func:`serve` is a wrapper around the event loop's
:meth:`~asyncio.loop.create_server` method. It creates and starts a
:class:`~asyncio.Server` with :meth:`~asyncio.loop.create_server`. Then it
wraps the :class:`~asyncio.Server` in a :class:`WebSocketServer` and
returns the :class:`WebSocketServer`.
The ``ws_handler`` argument is the WebSocket handler. It must be a
coroutine accepting two arguments: a :class:`WebSocketServerProtocol` and
the request URI.
The ``host`` and ``port`` arguments, as well as unrecognized keyword
arguments, are passed along to :meth:`~asyncio.loop.create_server`.
For example, you can set the ``ssl`` keyword argument to a
:class:`~ssl.SSLContext` to enable TLS.
The ``create_protocol`` parameter allows customizing the
:class:`~asyncio.Protocol` that manages the connection. It should be a
callable or class accepting the same arguments as
:class:`WebSocketServerProtocol` and returning an instance of
:class:`WebSocketServerProtocol` or a subclass. It defaults to
:class:`WebSocketServerProtocol`.
The behavior of ``ping_interval``, ``ping_timeout``, ``close_timeout``,
``max_size``, ``max_queue``, ``read_limit``, and ``write_limit`` is
described in :class:`~websockets.protocol.WebSocketCommonProtocol`.
:func:`serve` also accepts the following optional arguments:
* ``compression`` is a shortcut to configure compression extensions;
by default it enables the "permessage-deflate" extension; set it to
``None`` to disable compression
* ``origins`` defines acceptable Origin HTTP headers; include ``None`` if
the lack of an origin is acceptable
* ``extensions`` is a list of supported extensions in order of
decreasing preference
* ``subprotocols`` is a list of supported subprotocols in order of
decreasing preference
* ``extra_headers`` sets additional HTTP response headers when the
handshake succeeds; it can be a :class:`~websockets.http.Headers`
instance, a :class:`~collections.abc.Mapping`, an iterable of ``(name,
value)`` pairs, or a callable taking the request path and headers in
arguments and returning one of the above
* ``process_request`` allows intercepting the HTTP request; it must be a
coroutine taking the request path and headers in argument; see
:meth:`~WebSocketServerProtocol.process_request` for details
* ``select_subprotocol`` allows customizing the logic for selecting a
subprotocol; it must be a callable taking the subprotocols offered by
the client and available on the server in argument; see
:meth:`~WebSocketServerProtocol.select_subprotocol` for details
Since there's no useful way to propagate exceptions triggered in handlers,
they're sent to the ``'websockets.server'`` logger instead. Debugging is
much easier if you configure logging to print them::
import logging
logger = logging.getLogger('websockets.server')
logger.setLevel(logging.ERROR)
logger.addHandler(logging.StreamHandler())
"""
def __init__(
self,
ws_handler: Callable[[WebSocketServerProtocol, str], Awaitable[Any]],
host: Optional[Union[str, Sequence[str]]] = None,
port: Optional[int] = None,
*,
path: Optional[str] = None,
create_protocol: Optional[Type[WebSocketServerProtocol]] = None,
ping_interval: float = 20,
ping_timeout: float = 20,
close_timeout: Optional[float] = None,
max_size: int = 2 ** 20,
max_queue: int = 2 ** 5,
read_limit: int = 2 ** 16,
write_limit: int = 2 ** 16,
loop: Optional[asyncio.AbstractEventLoop] = None,
legacy_recv: bool = False,
klass: Optional[Type[WebSocketServerProtocol]] = None,
timeout: Optional[float] = None,
compression: Optional[str] = "deflate",
origins: Optional[Sequence[Optional[Origin]]] = None,
extensions: Optional[Sequence[ServerExtensionFactory]] = None,
subprotocols: Optional[Sequence[Subprotocol]] = None,
extra_headers: Optional[HeadersLikeOrCallable] = None,
process_request: Optional[
Callable[[str, Headers], Awaitable[Optional[HTTPResponse]]]
] = None,
select_subprotocol: Optional[
Callable[[Sequence[Subprotocol], Sequence[Subprotocol]], Subprotocol]
] = None,
**kwargs: Any,
) -> None:
# Backwards compatibility: close_timeout used to be called timeout.
if timeout is None:
timeout = 10
else:
warnings.warn("rename timeout to close_timeout", DeprecationWarning)
# If both are specified, timeout is ignored.
if close_timeout is None:
close_timeout = timeout
# Backwards compatibility: create_protocol used to be called klass.
if klass is None:
klass = WebSocketServerProtocol
else:
warnings.warn("rename klass to create_protocol", DeprecationWarning)
# If both are specified, klass is ignored.
if create_protocol is None:
create_protocol = klass
if loop is None:
loop = asyncio.get_event_loop()
ws_server = WebSocketServer(loop)
secure = kwargs.get("ssl") is not None
if compression == "deflate":
if extensions is None:
extensions = []
if not any(
ext_factory.name == ServerPerMessageDeflateFactory.name
for ext_factory in extensions
):
extensions = list(extensions) + [ServerPerMessageDeflateFactory()]
elif compression is not None:
raise ValueError(f"unsupported compression: {compression}")
factory = functools.partial(
create_protocol,
ws_handler,
ws_server,
host=host,
port=port,
secure=secure,
ping_interval=ping_interval,
ping_timeout=ping_timeout,
close_timeout=close_timeout,
max_size=max_size,
max_queue=max_queue,
read_limit=read_limit,
write_limit=write_limit,
loop=loop,
legacy_recv=legacy_recv,
origins=origins,
extensions=extensions,
subprotocols=subprotocols,
extra_headers=extra_headers,
process_request=process_request,
select_subprotocol=select_subprotocol,
)
if path is None:
create_server = functools.partial(
loop.create_server, factory, host, port, **kwargs
)
else:
# unix_serve(path) must not specify host and port parameters.
assert host is None and port is None
create_server = functools.partial(
loop.create_unix_server, factory, path, **kwargs
)
# This is a coroutine function.
self._create_server = create_server
self.ws_server = ws_server
# async with serve(...)
async def __aenter__(self) -> WebSocketServer:
return await self
async def __aexit__(
self,
exc_type: Optional[Type[BaseException]],
exc_value: Optional[BaseException],
traceback: Optional[TracebackType],
) -> None:
self.ws_server.close()
await self.ws_server.wait_closed()
# await serve(...)
def __await__(self) -> Generator[Any, None, WebSocketServer]:
# Create a suitable iterator by calling __await__ on a coroutine.
return self.__await_impl__().__await__()
async def __await_impl__(self) -> WebSocketServer:
server = await self._create_server()
self.ws_server.wrap(server)
return self.ws_server
# yield from serve(...)
__iter__ = __await__
serve = Serve
def unix_serve(
ws_handler: Callable[[WebSocketServerProtocol, str], Awaitable[Any]],
path: str,
**kwargs: Any,
) -> Serve:
"""
Similar to :func:`serve`, but for listening on Unix sockets.
This function calls the event loop's
:meth:`~asyncio.loop.create_unix_server` method.
It is only available on Unix.
It's useful for deploying a server behind a reverse proxy such as nginx.
:param path: file system path to the Unix socket
"""
return serve(ws_handler, path=path, **kwargs)
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 011453 x ustar 00 0000000 0000000 22 mtime=1561221850.0
websockets-8.1/src/websockets/speedups.c 0000644 0000765 0000024 00000012332 00000000000 020414 0 ustar 00myk staff 0000000 0000000 /* C implementation of performance sensitive functions. */
#define PY_SSIZE_T_CLEAN
#include
#include /* uint32_t, uint64_t */
#if __SSE2__
#include
#endif
static const Py_ssize_t MASK_LEN = 4;
/* Similar to PyBytes_AsStringAndSize, but accepts more types */
static int
_PyBytesLike_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)
{
// This supports bytes, bytearrays, and C-contiguous memoryview objects,
// which are the most useful data structures for handling byte streams.
// websockets.framing.prepare_data() returns only values of these types.
// Any object implementing the buffer protocol could be supported, however
// that would require allocation or copying memory, which is expensive.
if (PyBytes_Check(obj))
{
*buffer = PyBytes_AS_STRING(obj);
*length = PyBytes_GET_SIZE(obj);
}
else if (PyByteArray_Check(obj))
{
*buffer = PyByteArray_AS_STRING(obj);
*length = PyByteArray_GET_SIZE(obj);
}
else if (PyMemoryView_Check(obj))
{
Py_buffer *mv_buf;
mv_buf = PyMemoryView_GET_BUFFER(obj);
if (PyBuffer_IsContiguous(mv_buf, 'C'))
{
*buffer = mv_buf->buf;
*length = mv_buf->len;
}
else
{
PyErr_Format(
PyExc_TypeError,
"expected a contiguous memoryview");
return -1;
}
}
else
{
PyErr_Format(
PyExc_TypeError,
"expected a bytes-like object, %.200s found",
Py_TYPE(obj)->tp_name);
return -1;
}
return 0;
}
/* C implementation of websockets.utils.apply_mask */
static PyObject *
apply_mask(PyObject *self, PyObject *args, PyObject *kwds)
{
// In order to support various bytes-like types, accept any Python object.
static char *kwlist[] = {"data", "mask", NULL};
PyObject *input_obj;
PyObject *mask_obj;
// A pointer to a char * + length will be extracted from the data and mask
// arguments, possibly via a Py_buffer.
char *input;
Py_ssize_t input_len;
char *mask;
Py_ssize_t mask_len;
// Initialize a PyBytesObject then get a pointer to the underlying char *
// in order to avoid an extra memory copy in PyBytes_FromStringAndSize.
PyObject *result;
char *output;
// Other variables.
Py_ssize_t i = 0;
// Parse inputs.
if (!PyArg_ParseTupleAndKeywords(
args, kwds, "OO", kwlist, &input_obj, &mask_obj))
{
return NULL;
}
if (_PyBytesLike_AsStringAndSize(input_obj, &input, &input_len) == -1)
{
return NULL;
}
if (_PyBytesLike_AsStringAndSize(mask_obj, &mask, &mask_len) == -1)
{
return NULL;
}
if (mask_len != MASK_LEN)
{
PyErr_SetString(PyExc_ValueError, "mask must contain 4 bytes");
return NULL;
}
// Create output.
result = PyBytes_FromStringAndSize(NULL, input_len);
if (result == NULL)
{
return NULL;
}
// Since we juste created result, we don't need error checks.
output = PyBytes_AS_STRING(result);
// Perform the masking operation.
// Apparently GCC cannot figure out the following optimizations by itself.
// We need a new scope for MSVC 2010 (non C99 friendly)
{
#if __SSE2__
// With SSE2 support, XOR by blocks of 16 bytes = 128 bits.
// Since we cannot control the 16-bytes alignment of input and output
// buffers, we rely on loadu/storeu rather than load/store.
Py_ssize_t input_len_128 = input_len & ~15;
__m128i mask_128 = _mm_set1_epi32(*(uint32_t *)mask);
for (; i < input_len_128; i += 16)
{
__m128i in_128 = _mm_loadu_si128((__m128i *)(input + i));
__m128i out_128 = _mm_xor_si128(in_128, mask_128);
_mm_storeu_si128((__m128i *)(output + i), out_128);
}
#else
// Without SSE2 support, XOR by blocks of 8 bytes = 64 bits.
// We assume the memory allocator aligns everything on 8 bytes boundaries.
Py_ssize_t input_len_64 = input_len & ~7;
uint32_t mask_32 = *(uint32_t *)mask;
uint64_t mask_64 = ((uint64_t)mask_32 << 32) | (uint64_t)mask_32;
for (; i < input_len_64; i += 8)
{
*(uint64_t *)(output + i) = *(uint64_t *)(input + i) ^ mask_64;
}
#endif
}
// XOR the remainder of the input byte by byte.
for (; i < input_len; i++)
{
output[i] = input[i] ^ mask[i & (MASK_LEN - 1)];
}
return result;
}
static PyMethodDef speedups_methods[] = {
{
"apply_mask",
(PyCFunction)apply_mask,
METH_VARARGS | METH_KEYWORDS,
"Apply masking to websocket message.",
},
{NULL, NULL, 0, NULL}, /* Sentinel */
};
static struct PyModuleDef speedups_module = {
PyModuleDef_HEAD_INIT,
"websocket.speedups", /* m_name */
"C implementation of performance sensitive functions.",
/* m_doc */
-1, /* m_size */
speedups_methods, /* m_methods */
NULL,
NULL,
NULL,
NULL
};
PyMODINIT_FUNC
PyInit_speedups(void)
{
return PyModule_Create(&speedups_module);
}
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 011453 x ustar 00 0000000 0000000 22 mtime=1571084468.0
websockets-8.1/src/websockets/typing.py 0000644 0000765 0000024 00000002431 00000000000 020303 0 ustar 00myk staff 0000000 0000000 from typing import List, NewType, Optional, Tuple, Union
__all__ = ["Data", "Origin", "ExtensionHeader", "ExtensionParameter", "Subprotocol"]
Data = Union[str, bytes]
Data__doc__ = """
Types supported in a WebSocket message:
- :class:`str` for text messages
- :class:`bytes` for binary messages
"""
# Remove try / except when dropping support for Python < 3.7
try:
Data.__doc__ = Data__doc__ # type: ignore
except AttributeError: # pragma: no cover
pass
Origin = NewType("Origin", str)
Origin.__doc__ = """Value of a Origin header"""
ExtensionName = NewType("ExtensionName", str)
ExtensionName.__doc__ = """Name of a WebSocket extension"""
ExtensionParameter = Tuple[str, Optional[str]]
ExtensionParameter__doc__ = """Parameter of a WebSocket extension"""
try:
ExtensionParameter.__doc__ = ExtensionParameter__doc__ # type: ignore
except AttributeError: # pragma: no cover
pass
ExtensionHeader = Tuple[ExtensionName, List[ExtensionParameter]]
ExtensionHeader__doc__ = """Item parsed in a Sec-WebSocket-Extensions header"""
try:
ExtensionHeader.__doc__ = ExtensionHeader__doc__ # type: ignore
except AttributeError: # pragma: no cover
pass
Subprotocol = NewType("Subprotocol", str)
Subprotocol.__doc__ = """Items parsed in a Sec-WebSocket-Protocol header"""
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 011453 x ustar 00 0000000 0000000 22 mtime=1572601971.0
websockets-8.1/src/websockets/uri.py 0000644 0000765 0000024 00000004304 00000000000 017571 0 ustar 00myk staff 0000000 0000000 """
:mod:`websockets.uri` parses WebSocket URIs.
See `section 3 of RFC 6455`_.
.. _section 3 of RFC 6455: http://tools.ietf.org/html/rfc6455#section-3
"""
import urllib.parse
from typing import NamedTuple, Optional, Tuple
from .exceptions import InvalidURI
__all__ = ["parse_uri", "WebSocketURI"]
# Consider converting to a dataclass when dropping support for Python < 3.7.
class WebSocketURI(NamedTuple):
"""
WebSocket URI.
:param bool secure: secure flag
:param str host: lower-case host
:param int port: port, always set even if it's the default
:param str resource_name: path and optional query
:param str user_info: ``(username, password)`` tuple when the URI contains
`User Information`_, else ``None``.
.. _User Information: https://tools.ietf.org/html/rfc3986#section-3.2.1
"""
secure: bool
host: str
port: int
resource_name: str
user_info: Optional[Tuple[str, str]]
# Work around https://bugs.python.org/issue19931
WebSocketURI.secure.__doc__ = ""
WebSocketURI.host.__doc__ = ""
WebSocketURI.port.__doc__ = ""
WebSocketURI.resource_name.__doc__ = ""
WebSocketURI.user_info.__doc__ = ""
def parse_uri(uri: str) -> WebSocketURI:
"""
Parse and validate a WebSocket URI.
:raises ValueError: if ``uri`` isn't a valid WebSocket URI.
"""
parsed = urllib.parse.urlparse(uri)
try:
assert parsed.scheme in ["ws", "wss"]
assert parsed.params == ""
assert parsed.fragment == ""
assert parsed.hostname is not None
except AssertionError as exc:
raise InvalidURI(uri) from exc
secure = parsed.scheme == "wss"
host = parsed.hostname
port = parsed.port or (443 if secure else 80)
resource_name = parsed.path or "/"
if parsed.query:
resource_name += "?" + parsed.query
user_info = None
if parsed.username is not None:
# urllib.parse.urlparse accepts URLs with a username but without a
# password. This doesn't make sense for HTTP Basic Auth credentials.
if parsed.password is None:
raise InvalidURI(uri)
user_info = (parsed.username, parsed.password)
return WebSocketURI(secure, host, port, resource_name, user_info)
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 011453 x ustar 00 0000000 0000000 22 mtime=1571084468.0
websockets-8.1/src/websockets/utils.py 0000644 0000765 0000024 00000000570 00000000000 020133 0 ustar 00myk staff 0000000 0000000 import itertools
__all__ = ["apply_mask"]
def apply_mask(data: bytes, mask: bytes) -> bytes:
"""
Apply masking to the data of a WebSocket message.
:param data: Data to mask
:param mask: 4-bytes mask
"""
if len(mask) != 4:
raise ValueError("mask must contain 4 bytes")
return bytes(b ^ m for b, m in zip(data, itertools.cycle(mask)))
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 011453 x ustar 00 0000000 0000000 22 mtime=1572615511.0
websockets-8.1/src/websockets/version.py 0000644 0000765 0000024 00000000020 00000000000 020446 0 ustar 00myk staff 0000000 0000000 version = "8.1"
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 011452 x ustar 00 0000000 0000000 28 mtime=1572615610.4754937
websockets-8.1/src/websockets.egg-info/ 0000755 0000765 0000024 00000000000 00000000000 020111 5 ustar 00myk staff 0000000 0000000 ././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 011453 x ustar 00 0000000 0000000 22 mtime=1572615610.0
websockets-8.1/src/websockets.egg-info/PKG-INFO 0000644 0000765 0000024 00000016303 00000000000 021211 0 ustar 00myk staff 0000000 0000000 Metadata-Version: 1.2
Name: websockets
Version: 8.1
Summary: An implementation of the WebSocket Protocol (RFC 6455 & 7692)
Home-page: https://github.com/aaugustin/websockets
Author: Aymeric Augustin
Author-email: aymeric.augustin@m4x.org
License: BSD
Description: .. image:: logo/horizontal.svg
:width: 480px
:alt: websockets
|rtd| |pypi-v| |pypi-pyversions| |pypi-l| |pypi-wheel| |circleci| |codecov|
.. |rtd| image:: https://readthedocs.org/projects/websockets/badge/?version=latest
:target: https://websockets.readthedocs.io/
.. |pypi-v| image:: https://img.shields.io/pypi/v/websockets.svg
:target: https://pypi.python.org/pypi/websockets
.. |pypi-pyversions| image:: https://img.shields.io/pypi/pyversions/websockets.svg
:target: https://pypi.python.org/pypi/websockets
.. |pypi-l| image:: https://img.shields.io/pypi/l/websockets.svg
:target: https://pypi.python.org/pypi/websockets
.. |pypi-wheel| image:: https://img.shields.io/pypi/wheel/websockets.svg
:target: https://pypi.python.org/pypi/websockets
.. |circleci| image:: https://img.shields.io/circleci/project/github/aaugustin/websockets.svg
:target: https://circleci.com/gh/aaugustin/websockets
.. |codecov| image:: https://codecov.io/gh/aaugustin/websockets/branch/master/graph/badge.svg
:target: https://codecov.io/gh/aaugustin/websockets
What is ``websockets``?
-----------------------
``websockets`` is a library for building WebSocket servers_ and clients_ in
Python with a focus on correctness and simplicity.
.. _servers: https://github.com/aaugustin/websockets/blob/master/example/server.py
.. _clients: https://github.com/aaugustin/websockets/blob/master/example/client.py
Built on top of ``asyncio``, Python's standard asynchronous I/O framework, it
provides an elegant coroutine-based API.
`Documentation is available on Read the Docs. `_
Here's how a client sends and receives messages:
.. copy-pasted because GitHub doesn't support the include directive
.. code:: python
#!/usr/bin/env python
import asyncio
import websockets
async def hello(uri):
async with websockets.connect(uri) as websocket:
await websocket.send("Hello world!")
await websocket.recv()
asyncio.get_event_loop().run_until_complete(
hello('ws://localhost:8765'))
And here's an echo server:
.. code:: python
#!/usr/bin/env python
import asyncio
import websockets
async def echo(websocket, path):
async for message in websocket:
await websocket.send(message)
asyncio.get_event_loop().run_until_complete(
websockets.serve(echo, 'localhost', 8765))
asyncio.get_event_loop().run_forever()
Does that look good?
`Get started with the tutorial! `_
Why should I use ``websockets``?
--------------------------------
The development of ``websockets`` is shaped by four principles:
1. **Simplicity**: all you need to understand is ``msg = await ws.recv()`` and
``await ws.send(msg)``; ``websockets`` takes care of managing connections
so you can focus on your application.
2. **Robustness**: ``websockets`` is built for production; for example it was
the only library to `handle backpressure correctly`_ before the issue
became widely known in the Python community.
3. **Quality**: ``websockets`` is heavily tested. Continuous integration fails
under 100% branch coverage. Also it passes the industry-standard `Autobahn
Testsuite`_.
4. **Performance**: memory use is configurable. An extension written in C
accelerates expensive operations. It's pre-compiled for Linux, macOS and
Windows and packaged in the wheel format for each system and Python version.
Documentation is a first class concern in the project. Head over to `Read the
Docs`_ and see for yourself.
.. _Read the Docs: https://websockets.readthedocs.io/
.. _handle backpressure correctly: https://vorpus.org/blog/some-thoughts-on-asynchronous-api-design-in-a-post-asyncawait-world/#websocket-servers
.. _Autobahn Testsuite: https://github.com/aaugustin/websockets/blob/master/compliance/README.rst
Why shouldn't I use ``websockets``?
-----------------------------------
* If you prefer callbacks over coroutines: ``websockets`` was created to
provide the best coroutine-based API to manage WebSocket connections in
Python. Pick another library for a callback-based API.
* If you're looking for a mixed HTTP / WebSocket library: ``websockets`` aims
at being an excellent implementation of :rfc:`6455`: The WebSocket Protocol
and :rfc:`7692`: Compression Extensions for WebSocket. Its support for HTTP
is minimal — just enough for a HTTP health check.
* If you want to use Python 2: ``websockets`` builds upon ``asyncio`` which
only works on Python 3. ``websockets`` requires Python ≥ 3.6.1.
What else?
----------
Bug reports, patches and suggestions are welcome!
To report a security vulnerability, please use the `Tidelift security
contact`_. Tidelift will coordinate the fix and disclosure.
.. _Tidelift security contact: https://tidelift.com/security
For anything else, please open an issue_ or send a `pull request`_.
.. _issue: https://github.com/aaugustin/websockets/issues/new
.. _pull request: https://github.com/aaugustin/websockets/compare/
Participants must uphold the `Contributor Covenant code of conduct`_.
.. _Contributor Covenant code of conduct: https://github.com/aaugustin/websockets/blob/master/CODE_OF_CONDUCT.md
``websockets`` is released under the `BSD license`_.
.. _BSD license: https://github.com/aaugustin/websockets/blob/master/LICENSE
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Requires-Python: >=3.6.1
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 011453 x ustar 00 0000000 0000000 22 mtime=1572615610.0
websockets-8.1/src/websockets.egg-info/SOURCES.txt 0000644 0000765 0000024 00000001427 00000000000 022001 0 ustar 00myk staff 0000000 0000000 LICENSE
MANIFEST.in
README.rst
setup.cfg
setup.py
src/websockets/__init__.py
src/websockets/__main__.py
src/websockets/auth.py
src/websockets/client.py
src/websockets/exceptions.py
src/websockets/framing.py
src/websockets/handshake.py
src/websockets/headers.py
src/websockets/http.py
src/websockets/protocol.py
src/websockets/py.typed
src/websockets/server.py
src/websockets/speedups.c
src/websockets/typing.py
src/websockets/uri.py
src/websockets/utils.py
src/websockets/version.py
src/websockets.egg-info/PKG-INFO
src/websockets.egg-info/SOURCES.txt
src/websockets.egg-info/dependency_links.txt
src/websockets.egg-info/not-zip-safe
src/websockets.egg-info/top_level.txt
src/websockets/extensions/__init__.py
src/websockets/extensions/base.py
src/websockets/extensions/permessage_deflate.py ././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 011453 x ustar 00 0000000 0000000 22 mtime=1572615610.0
websockets-8.1/src/websockets.egg-info/dependency_links.txt 0000644 0000765 0000024 00000000001 00000000000 024157 0 ustar 00myk staff 0000000 0000000
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 011453 x ustar 00 0000000 0000000 22 mtime=1570900839.0
websockets-8.1/src/websockets.egg-info/not-zip-safe 0000644 0000765 0000024 00000000001 00000000000 022337 0 ustar 00myk staff 0000000 0000000
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 011453 x ustar 00 0000000 0000000 22 mtime=1572615610.0
websockets-8.1/src/websockets.egg-info/top_level.txt 0000644 0000765 0000024 00000000041 00000000000 022636 0 ustar 00myk staff 0000000 0000000 websockets
websockets/extensions