././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1622143564.0407488
websockets-9.1/ 0000755 0001751 0000171 00000000000 00000000000 013074 5 ustar 00runner docker ././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/LICENSE 0000644 0001751 0000171 00000003000 00000000000 014072 0 ustar 00runner docker Copyright (c) 2013-2021 Aymeric Augustin and contributors.
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
* Neither the name of websockets nor the names of its contributors may
be used to endorse or promote products derived from this software without
specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/MANIFEST.in 0000644 0001751 0000171 00000000060 00000000000 014626 0 ustar 00runner docker include LICENSE
include src/websockets/py.typed
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1622143564.0407488
websockets-9.1/PKG-INFO 0000644 0001751 0000171 00000016120 00000000000 014171 0 ustar 00runner docker Metadata-Version: 1.2
Name: websockets
Version: 9.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| |tests|
.. |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
.. |tests| image:: https://github.com/aaugustin/websockets/workflows/tests/badge.svg?branch=master
:target: https://github.com/aaugustin/websockets/actions?workflow=tests
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
Classifier: Programming Language :: Python :: 3.9
Requires-Python: >=3.6.1
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/README.rst 0000644 0001751 0000171 00000014153 00000000000 014567 0 ustar 00runner docker .. image:: logo/horizontal.svg
:width: 480px
:alt: websockets
|rtd| |pypi-v| |pypi-pyversions| |pypi-l| |pypi-wheel| |tests|
.. |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
.. |tests| image:: https://github.com/aaugustin/websockets/workflows/tests/badge.svg?branch=master
:target: https://github.com/aaugustin/websockets/actions?workflow=tests
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! `_
.. 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 010212 x ustar 00 28 mtime=1622143564.0407488
websockets-9.1/setup.cfg 0000644 0001751 0000171 00000000656 00000000000 014724 0 ustar 00runner docker [bdist_wheel]
python-tag = py36.py37.py38.py39
[metadata]
license_file = LICENSE
[flake8]
ignore = E203,E731,F403,F405,W503
max-line-length = 88
[isort]
profile = black
combine_as_imports = True
lines_after_imports = 2
[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 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/setup.py 0000644 0001751 0000171 00000003625 00000000000 014614 0 ustar 00runner docker 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/legacy', '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',
'Programming Language :: Python :: 3.9',
],
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 00000000034 00000000000 010212 x ustar 00 28 mtime=1622143564.0327487
websockets-9.1/src/ 0000755 0001751 0000171 00000000000 00000000000 013663 5 ustar 00runner docker ././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1622143564.0367486
websockets-9.1/src/websockets/ 0000755 0001751 0000171 00000000000 00000000000 016034 5 ustar 00runner docker ././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/src/websockets/__init__.py 0000644 0001751 0000171 00000006240 00000000000 020147 0 ustar 00runner docker from .imports import lazy_import
from .version import version as __version__ # noqa
__all__ = [ # noqa
"AbortHandshake",
"basic_auth_protocol_factory",
"BasicAuthWebSocketServerProtocol",
"ClientConnection",
"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",
"ServerConnection",
"Subprotocol",
"unix_connect",
"unix_serve",
"WebSocketClientProtocol",
"WebSocketCommonProtocol",
"WebSocketException",
"WebSocketProtocolError",
"WebSocketServer",
"WebSocketServerProtocol",
"WebSocketURI",
]
lazy_import(
globals(),
aliases={
"auth": ".legacy",
"basic_auth_protocol_factory": ".legacy.auth",
"BasicAuthWebSocketServerProtocol": ".legacy.auth",
"ClientConnection": ".client",
"connect": ".legacy.client",
"unix_connect": ".legacy.client",
"WebSocketClientProtocol": ".legacy.client",
"Headers": ".datastructures",
"MultipleValuesError": ".datastructures",
"WebSocketException": ".exceptions",
"ConnectionClosed": ".exceptions",
"ConnectionClosedError": ".exceptions",
"ConnectionClosedOK": ".exceptions",
"InvalidHandshake": ".exceptions",
"SecurityError": ".exceptions",
"InvalidMessage": ".exceptions",
"InvalidHeader": ".exceptions",
"InvalidHeaderFormat": ".exceptions",
"InvalidHeaderValue": ".exceptions",
"InvalidOrigin": ".exceptions",
"InvalidUpgrade": ".exceptions",
"InvalidStatusCode": ".exceptions",
"NegotiationError": ".exceptions",
"DuplicateParameter": ".exceptions",
"InvalidParameterName": ".exceptions",
"InvalidParameterValue": ".exceptions",
"AbortHandshake": ".exceptions",
"RedirectHandshake": ".exceptions",
"InvalidState": ".exceptions",
"InvalidURI": ".exceptions",
"PayloadTooBig": ".exceptions",
"ProtocolError": ".exceptions",
"WebSocketProtocolError": ".exceptions",
"protocol": ".legacy",
"WebSocketCommonProtocol": ".legacy.protocol",
"ServerConnection": ".server",
"serve": ".legacy.server",
"unix_serve": ".legacy.server",
"WebSocketServerProtocol": ".legacy.server",
"WebSocketServer": ".legacy.server",
"Data": ".typing",
"Origin": ".typing",
"ExtensionHeader": ".typing",
"ExtensionParameter": ".typing",
"Subprotocol": ".typing",
},
deprecated_aliases={
"framing": ".legacy",
"handshake": ".legacy",
"parse_uri": ".uri",
"WebSocketURI": ".uri",
},
)
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/src/websockets/__main__.py 0000644 0001751 0000171 00000015223 00000000000 020131 0 ustar 00runner docker import argparse
import asyncio
import os
import signal
import sys
import threading
from typing import Any, Set
from .exceptions import ConnectionClosed, format_close
from .legacy.client import connect
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.
if sys.platform == "win32":
ctrl_c = signal.CTRL_C_EVENT
else:
ctrl_c = signal.SIGINT
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()
# Due to zealous removal of the loop parameter in the Queue constructor,
# we need a factory coroutine to run in the freshly created event loop.
async def queue_factory() -> "asyncio.Queue[str]":
return asyncio.Queue()
# Create a queue of user inputs. There's no need to limit its size.
inputs: "asyncio.Queue[str]" = loop.run_until_complete(queue_factory())
# 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()
# For reasons unclear, even though the loop is closed in the thread,
# it still thinks it's running here.
loop.close()
if __name__ == "__main__":
main()
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/src/websockets/auth.py 0000644 0001751 0000171 00000000157 00000000000 017352 0 ustar 00runner docker # See #940 for why lazy_import isn't used here for backwards compatibility.
from .legacy.auth import * # noqa
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/src/websockets/client.py 0000644 0001751 0000171 00000024036 00000000000 017671 0 ustar 00runner docker import collections
import logging
from typing import Generator, List, Optional, Sequence
from .connection import CLIENT, CONNECTING, OPEN, Connection
from .datastructures import Headers, HeadersLike, MultipleValuesError
from .exceptions import (
InvalidHandshake,
InvalidHeader,
InvalidHeaderValue,
InvalidStatusCode,
InvalidUpgrade,
NegotiationError,
)
from .extensions.base import ClientExtensionFactory, Extension
from .headers import (
build_authorization_basic,
build_extension,
build_subprotocol,
parse_connection,
parse_extension,
parse_subprotocol,
parse_upgrade,
)
from .http import USER_AGENT, build_host
from .http11 import Request, Response
from .typing import (
ConnectionOption,
ExtensionHeader,
Origin,
Subprotocol,
UpgradeProtocol,
)
from .uri import parse_uri
from .utils import accept_key, generate_key
# See #940 for why lazy_import isn't used here for backwards compatibility.
from .legacy.client import * # isort:skip # noqa
__all__ = ["ClientConnection"]
logger = logging.getLogger(__name__)
class ClientConnection(Connection):
def __init__(
self,
uri: str,
origin: Optional[Origin] = None,
extensions: Optional[Sequence[ClientExtensionFactory]] = None,
subprotocols: Optional[Sequence[Subprotocol]] = None,
extra_headers: Optional[HeadersLike] = None,
max_size: Optional[int] = 2 ** 20,
):
super().__init__(side=CLIENT, state=CONNECTING, max_size=max_size)
self.wsuri = parse_uri(uri)
self.origin = origin
self.available_extensions = extensions
self.available_subprotocols = subprotocols
self.extra_headers = extra_headers
self.key = generate_key()
def connect(self) -> Request: # noqa: F811
"""
Create a WebSocket handshake request event to send to the server.
"""
headers = Headers()
headers["Host"] = build_host(
self.wsuri.host, self.wsuri.port, self.wsuri.secure
)
if self.wsuri.user_info:
headers["Authorization"] = build_authorization_basic(*self.wsuri.user_info)
if self.origin is not None:
headers["Origin"] = self.origin
headers["Upgrade"] = "websocket"
headers["Connection"] = "Upgrade"
headers["Sec-WebSocket-Key"] = self.key
headers["Sec-WebSocket-Version"] = "13"
if self.available_extensions is not None:
extensions_header = build_extension(
[
(extension_factory.name, extension_factory.get_request_params())
for extension_factory in self.available_extensions
]
)
headers["Sec-WebSocket-Extensions"] = extensions_header
if self.available_subprotocols is not None:
protocol_header = build_subprotocol(self.available_subprotocols)
headers["Sec-WebSocket-Protocol"] = protocol_header
if self.extra_headers is not None:
extra_headers = self.extra_headers
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:
headers[name] = value
headers.setdefault("User-Agent", USER_AGENT)
return Request(self.wsuri.resource_name, headers)
def process_response(self, response: Response) -> None:
"""
Check a handshake response received from the server.
:param response: response
:param key: comes from :func:`build_request`
:raises ~websockets.exceptions.InvalidHandshake: if the handshake response
is invalid
"""
if response.status_code != 101:
raise InvalidStatusCode(response.status_code)
headers = response.headers
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) if connection else None
)
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) if upgrade else None)
try:
s_w_accept = headers["Sec-WebSocket-Accept"]
except KeyError as exc:
raise InvalidHeader("Sec-WebSocket-Accept") from exc
except MultipleValuesError as exc:
raise InvalidHeader(
"Sec-WebSocket-Accept",
"more than one Sec-WebSocket-Accept header found",
) from exc
if s_w_accept != accept_key(self.key):
raise InvalidHeaderValue("Sec-WebSocket-Accept", s_w_accept)
self.extensions = self.process_extensions(headers)
self.subprotocol = self.process_subprotocol(headers)
def process_extensions(self, headers: Headers) -> 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] = []
extensions = headers.get_all("Sec-WebSocket-Extensions")
if extensions:
if self.available_extensions is None:
raise InvalidHandshake("no extensions supported")
parsed_extensions: List[ExtensionHeader] = sum(
[parse_extension(header_value) for header_value in extensions], []
)
for name, response_params in parsed_extensions:
for extension_factory in self.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
def process_subprotocol(self, headers: Headers) -> 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
subprotocols = headers.get_all("Sec-WebSocket-Protocol")
if subprotocols:
if self.available_subprotocols is None:
raise InvalidHandshake("no subprotocols supported")
parsed_subprotocols: Sequence[Subprotocol] = sum(
[parse_subprotocol(header_value) for header_value in subprotocols], []
)
if len(parsed_subprotocols) > 1:
subprotocols_display = ", ".join(parsed_subprotocols)
raise InvalidHandshake(f"multiple subprotocols: {subprotocols_display}")
subprotocol = parsed_subprotocols[0]
if subprotocol not in self.available_subprotocols:
raise NegotiationError(f"unsupported subprotocol: {subprotocol}")
return subprotocol
def send_request(self, request: Request) -> None:
"""
Send a WebSocket handshake request to the server.
"""
logger.debug("%s > GET %s HTTP/1.1", self.side, request.path)
logger.debug("%s > %r", self.side, request.headers)
self.writes.append(request.serialize())
def parse(self) -> Generator[None, None, None]:
response = yield from Response.parse(
self.reader.read_line, self.reader.read_exact, self.reader.read_to_eof
)
assert self.state == CONNECTING
try:
self.process_response(response)
except InvalidHandshake as exc:
response = response._replace(exception=exc)
logger.debug("Invalid handshake", exc_info=True)
else:
self.set_state(OPEN)
finally:
self.events.append(response)
yield from super().parse()
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/src/websockets/connection.py 0000644 0001751 0000171 00000033201 00000000000 020544 0 ustar 00runner docker import enum
import logging
from typing import Generator, List, Optional, Union
from .exceptions import InvalidState, PayloadTooBig, ProtocolError
from .extensions.base import Extension
from .frames import (
OP_BINARY,
OP_CLOSE,
OP_CONT,
OP_PING,
OP_PONG,
OP_TEXT,
Frame,
parse_close,
serialize_close,
)
from .http11 import Request, Response
from .streams import StreamReader
from .typing import Origin, Subprotocol
__all__ = [
"Connection",
"Side",
"State",
"SEND_EOF",
]
logger = logging.getLogger(__name__)
Event = Union[Request, Response, Frame]
# A WebSocket connection is either a server or a client.
class Side(enum.IntEnum):
SERVER, CLIENT = range(2)
SERVER = Side.SERVER
CLIENT = Side.CLIENT
# A WebSocket connection goes through the following four states, in order:
class State(enum.IntEnum):
CONNECTING, OPEN, CLOSING, CLOSED = range(4)
CONNECTING = State.CONNECTING
OPEN = State.OPEN
CLOSING = State.CLOSING
CLOSED = State.CLOSED
# Sentinel to signal that the connection should be closed.
SEND_EOF = b""
class Connection:
def __init__(
self,
side: Side,
state: State = OPEN,
max_size: Optional[int] = 2 ** 20,
) -> None:
# Connection side. CLIENT or SERVER.
self.side = side
# Connnection state. CONNECTING and CLOSED states are handled in subclasses.
logger.debug("%s - initial state: %s", self.side, state.name)
self.state = state
# Maximum size of incoming messages in bytes.
self.max_size = max_size
# Current size of incoming message in bytes. Only set while reading a
# fragmented message i.e. a data frames with the FIN bit not set.
self.cur_size: Optional[int] = None
# True while sending a fragmented message i.e. a data frames with the
# FIN bit not set.
self.expect_continuation_frame = False
# WebSocket protocol parameters.
self.origin: Optional[Origin] = None
self.extensions: List[Extension] = []
self.subprotocol: Optional[Subprotocol] = None
# Connection state isn't enough to tell if a close frame was received:
# when this side closes the connection, state is CLOSING as soon as a
# close frame is sent, before a close frame is received.
self.close_frame_received = False
# Close code and reason. Set when receiving a close frame or when the
# TCP connection drops.
self.close_code: int
self.close_reason: str
# Track if send_eof() was called.
self.eof_sent = False
# Parser state.
self.reader = StreamReader()
self.events: List[Event] = []
self.writes: List[bytes] = []
self.parser = self.parse()
next(self.parser) # start coroutine
self.parser_exc: Optional[Exception] = None
def set_state(self, state: State) -> None:
logger.debug(
"%s - state change: %s > %s", self.side, self.state.name, state.name
)
self.state = state
# Public APIs for receiving data.
def receive_data(self, data: bytes) -> None:
"""
Receive data from the connection.
After calling this method:
- You must call :meth:`data_to_send` and send this data.
- You should call :meth:`events_received` and process these events.
"""
self.reader.feed_data(data)
self.step_parser()
def receive_eof(self) -> None:
"""
Receive the end of the data stream from the connection.
After calling this method:
- You must call :meth:`data_to_send` and send this data.
- You shouldn't call :meth:`events_received` as it won't
return any new events.
"""
self.reader.feed_eof()
self.step_parser()
# Public APIs for sending events.
def send_continuation(self, data: bytes, fin: bool) -> None:
"""
Send a continuation frame.
"""
if not self.expect_continuation_frame:
raise ProtocolError("unexpected continuation frame")
self.expect_continuation_frame = not fin
self.send_frame(Frame(fin, OP_CONT, data))
def send_text(self, data: bytes, fin: bool = True) -> None:
"""
Send a text frame.
"""
if self.expect_continuation_frame:
raise ProtocolError("expected a continuation frame")
self.expect_continuation_frame = not fin
self.send_frame(Frame(fin, OP_TEXT, data))
def send_binary(self, data: bytes, fin: bool = True) -> None:
"""
Send a binary frame.
"""
if self.expect_continuation_frame:
raise ProtocolError("expected a continuation frame")
self.expect_continuation_frame = not fin
self.send_frame(Frame(fin, OP_BINARY, data))
def send_close(self, code: Optional[int] = None, reason: str = "") -> None:
"""
Send a connection close frame.
"""
if self.expect_continuation_frame:
raise ProtocolError("expected a continuation frame")
if code is None:
if reason != "":
raise ValueError("cannot send a reason without a code")
data = b""
else:
data = serialize_close(code, reason)
self.send_frame(Frame(True, OP_CLOSE, data))
# send_frame() guarantees that self.state is OPEN at this point.
# 7.1.3. The WebSocket Closing Handshake is Started
self.set_state(CLOSING)
if self.side is SERVER:
self.send_eof()
def send_ping(self, data: bytes) -> None:
"""
Send a ping frame.
"""
self.send_frame(Frame(True, OP_PING, data))
def send_pong(self, data: bytes) -> None:
"""
Send a pong frame.
"""
self.send_frame(Frame(True, OP_PONG, data))
# Public API for getting incoming events after receiving data.
def events_received(self) -> List[Event]:
"""
Return events read from the connection.
Call this method immediately after calling any of the ``receive_*()``
methods and process the events.
"""
events, self.events = self.events, []
return events
# Public API for getting outgoing data after receiving data or sending events.
def data_to_send(self) -> List[bytes]:
"""
Return data to write to the connection.
Call this method immediately after calling any of the ``receive_*()``
or ``send_*()`` methods and write the data to the connection.
The empty bytestring signals the end of the data stream.
"""
writes, self.writes = self.writes, []
return writes
# Private APIs for receiving data.
def fail_connection(self, code: int = 1006, reason: str = "") -> None:
# 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.
if code != 1006 and self.state is OPEN:
self.send_frame(Frame(True, OP_CLOSE, serialize_close(code, reason)))
self.set_state(CLOSING)
if not self.eof_sent:
self.send_eof()
def step_parser(self) -> None:
# Run parser until more data is needed or EOF
try:
next(self.parser)
except StopIteration:
# This happens if receive_data() or receive_eof() is called after
# the parser raised an exception. (It cannot happen after reaching
# EOF because receive_data() or receive_eof() would fail earlier.)
assert self.parser_exc is not None
raise RuntimeError(
"cannot receive data or EOF after an error"
) from self.parser_exc
except ProtocolError as exc:
self.fail_connection(1002, str(exc))
self.parser_exc = exc
raise
except EOFError as exc:
self.fail_connection(1006, str(exc))
self.parser_exc = exc
raise
except UnicodeDecodeError as exc:
self.fail_connection(1007, f"{exc.reason} at position {exc.start}")
self.parser_exc = exc
raise
except PayloadTooBig as exc:
self.fail_connection(1009, str(exc))
self.parser_exc = exc
raise
except Exception as exc:
logger.error("unexpected exception in parser", exc_info=True)
# Don't include exception details, which may be security-sensitive.
self.fail_connection(1011)
self.parser_exc = exc
raise
def parse(self) -> Generator[None, None, None]:
while True:
eof = yield from self.reader.at_eof()
if eof:
if self.close_frame_received:
if not self.eof_sent:
self.send_eof()
yield
# Once the reader reaches EOF, its feed_data/eof() methods
# raise an error, so our receive_data/eof() methods never
# call step_parser(), so the generator shouldn't resume
# executing until it's garbage collected.
raise AssertionError(
"parser shouldn't step after EOF"
) # pragma: no cover
else:
raise EOFError("unexpected end of stream")
if self.max_size is None:
max_size = None
elif self.cur_size is None:
max_size = self.max_size
else:
max_size = self.max_size - self.cur_size
frame = yield from Frame.parse(
self.reader.read_exact,
mask=self.side is SERVER,
max_size=max_size,
extensions=self.extensions,
)
if frame.opcode is OP_TEXT or frame.opcode is OP_BINARY:
# 5.5.1 Close: "The application MUST NOT send any more data
# frames after sending a Close frame."
if self.close_frame_received:
raise ProtocolError("data frame after close frame")
if self.cur_size is not None:
raise ProtocolError("expected a continuation frame")
if frame.fin:
self.cur_size = None
else:
self.cur_size = len(frame.data)
elif frame.opcode is OP_CONT:
# 5.5.1 Close: "The application MUST NOT send any more data
# frames after sending a Close frame."
if self.close_frame_received:
raise ProtocolError("data frame after close frame")
if self.cur_size is None:
raise ProtocolError("unexpected continuation frame")
if frame.fin:
self.cur_size = None
else:
self.cur_size += len(frame.data)
elif frame.opcode is OP_PING:
# 5.5.2. Ping: "Upon receipt of a Ping frame, an endpoint MUST
# send a Pong frame in response, unless it already received a
# Close frame."
if not self.close_frame_received:
pong_frame = Frame(True, OP_PONG, frame.data)
self.send_frame(pong_frame)
elif frame.opcode is OP_PONG:
# 5.5.3 Pong: "A response to an unsolicited Pong frame is not
# expected."
pass
elif frame.opcode is OP_CLOSE:
self.close_frame_received = True
# 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)
if self.cur_size is not None:
raise ProtocolError("incomplete fragmented message")
# 5.5.1 Close: "If an endpoint receives a Close frame and did
# not previously send a Close frame, the endpoint MUST send a
# Close frame in response. (When sending a Close frame in
# response, the endpoint typically echos the status code it
# received.)"
if self.state is OPEN:
# 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.
# The rest is identical to send_close().
self.send_frame(Frame(True, OP_CLOSE, frame.data))
self.set_state(CLOSING)
if self.side is SERVER:
self.send_eof()
else: # pragma: no cover
# This can't happen because Frame.parse() validates opcodes.
raise AssertionError(f"unexpected opcode: {frame.opcode:02x}")
self.events.append(frame)
# Private APIs for sending events.
def send_frame(self, frame: Frame) -> None:
# Defensive assertion for protocol compliance.
if self.state is not OPEN:
raise InvalidState(
f"cannot write to a WebSocket in the {self.state.name} state"
)
logger.debug("%s > %r", self.side, frame)
self.writes.append(
frame.serialize(mask=self.side is CLIENT, extensions=self.extensions)
)
def send_eof(self) -> None:
assert not self.eof_sent
self.eof_sent = True
logger.debug("%s > EOF", self.side)
self.writes.append(SEND_EOF)
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/src/websockets/datastructures.py 0000644 0001751 0000171 00000011541 00000000000 021465 0 ustar 00runner docker """
:mod:`websockets.datastructures` defines a class for manipulating HTTP headers.
"""
from typing import (
Any,
Dict,
Iterable,
Iterator,
List,
Mapping,
MutableMapping,
Tuple,
Union,
)
__all__ = ["Headers", "HeadersLike", "MultipleValuesError"]
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 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
def serialize(self) -> bytes:
# Headers only contain ASCII characters.
return str(self).encode()
# 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]]]
HeadersLike__doc__ = """Types accepted wherever :class:`Headers` is expected"""
# Remove try / except when dropping support for Python < 3.7
try:
HeadersLike.__doc__ = HeadersLike__doc__
except AttributeError: # pragma: no cover
pass
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/src/websockets/exceptions.py 0000644 0001751 0000171 00000021457 00000000000 020600 0 ustar 00runner docker """
: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 .datastructures 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`.
"""
# See https://www.iana.org/assignments/websocket/websocket.xhtml
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",
1012: "service restart",
1013: "try again later",
1014: "bad gateway",
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:`~legacy.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 a frame breaks the protocol.
"""
WebSocketProtocolError = ProtocolError # for backwards compatibility
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1622143564.0367486
websockets-9.1/src/websockets/extensions/ 0000755 0001751 0000171 00000000000 00000000000 020233 5 ustar 00runner docker ././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/src/websockets/extensions/__init__.py 0000644 0001751 0000171 00000000142 00000000000 022341 0 ustar 00runner docker from .base import *
__all__ = ["Extension", "ClientExtensionFactory", "ServerExtensionFactory"]
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/src/websockets/extensions/base.py 0000644 0001751 0000171 00000005337 00000000000 021527 0 ustar 00runner docker """
: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 ..frames 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 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/src/websockets/extensions/permessage_deflate.py 0000644 0001751 0000171 00000055265 00000000000 024441 0 ustar 00runner docker """
: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 ..frames import CTRL_OPCODES, OP_CONT, Frame
from ..typing import ExtensionName, ExtensionParameter
from .base import ClientExtensionFactory, Extension, ServerExtensionFactory
__all__ = [
"PerMessageDeflate",
"ClientPerMessageDeflateFactory",
"enable_client_permessage_deflate",
"ServerPerMessageDeflateFactory",
"enable_server_permessage_deflate",
]
_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 message isn'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 message isn't encoded
# - unset the rsv1 flag on the first frame of a compressed message
# - set "decode continuation data" flag if it's a non-final frame
else:
if not frame.rsv1:
return frame
frame = frame._replace(rsv1=False)
if not frame.fin:
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 data. 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"over 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)
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 messages, there's no "encode continuation
# data" flag similar to "decode continuation data" at this time.
if frame.opcode != OP_CONT:
# Set the rsv1 flag on the first frame of a compressed message.
frame = frame._replace(rsv1=True)
# 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.
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)
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,
)
def enable_client_permessage_deflate(
extensions: Optional[Sequence[ClientExtensionFactory]],
) -> Sequence[ClientExtensionFactory]:
"""
Enable Per-Message Deflate with default settings in client extensions.
If the extension is already present, perhaps with non-default settings,
the configuration isn't changed.
"""
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)
]
return extensions
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 Sequence[ServerExtensionFactory]:
"""
Enable Per-Message Deflate with default settings in server extensions.
If the extension is already present, perhaps with non-default settings,
the configuration isn't changed.
"""
if extensions is None:
extensions = []
if not any(
ext_factory.name == ServerPerMessageDeflateFactory.name
for ext_factory in extensions
):
extensions = list(extensions) + [ServerPerMessageDeflateFactory()]
return extensions
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/src/websockets/frames.py 0000644 0001751 0000171 00000022356 00000000000 017673 0 ustar 00runner docker """
Parse and serialize WebSocket frames.
"""
import enum
import io
import secrets
import struct
from typing import Callable, Generator, NamedTuple, Optional, Sequence, Tuple
from .exceptions import PayloadTooBig, ProtocolError
from .typing import Data
try:
from .speedups import apply_mask
except ImportError: # pragma: no cover
from .utils import apply_mask
__all__ = [
"Opcode",
"OP_CONT",
"OP_TEXT",
"OP_BINARY",
"OP_CLOSE",
"OP_PING",
"OP_PONG",
"DATA_OPCODES",
"CTRL_OPCODES",
"Frame",
"prepare_data",
"prepare_ctrl",
"parse_close",
"serialize_close",
]
class Opcode(enum.IntEnum):
CONT, TEXT, BINARY = 0x00, 0x01, 0x02
CLOSE, PING, PONG = 0x08, 0x09, 0x0A
OP_CONT = Opcode.CONT
OP_TEXT = Opcode.TEXT
OP_BINARY = Opcode.BINARY
OP_CLOSE = Opcode.CLOSE
OP_PING = Opcode.PING
OP_PONG = Opcode.PONG
DATA_OPCODES = OP_CONT, OP_TEXT, OP_BINARY
CTRL_OPCODES = OP_CLOSE, OP_PING, OP_PONG
# Close code that are allowed in a close frame.
# Using a set optimizes `code in EXTERNAL_CLOSE_CODES`.
EXTERNAL_CLOSE_CODES = {
1000,
1001,
1002,
1003,
1007,
1008,
1009,
1010,
1011,
1012,
1013,
1014,
}
# Consider converting to a dataclass when dropping support for Python < 3.7.
class Frame(NamedTuple):
"""
WebSocket frame.
:param bool fin: FIN bit
:param bool rsv1: RSV1 bit
:param bool rsv2: RSV2 bit
:param bool rsv3: RSV3 bit
:param int opcode: opcode
:param bytes data: payload data
Only these fields are needed. The MASK bit, payload length and masking-key
are handled on the fly by :func:`parse_frame` and :meth:`serialize_frame`.
"""
fin: bool
opcode: Opcode
data: bytes
rsv1: bool = False
rsv2: bool = False
rsv3: bool = False
@classmethod
def parse(
cls,
read_exact: Callable[[int], Generator[None, None, bytes]],
*,
mask: bool,
max_size: Optional[int] = None,
extensions: Optional[Sequence["extensions.Extension"]] = None,
) -> Generator[None, None, "Frame"]:
"""
Read a WebSocket frame.
:param read_exact: generator-based coroutine that reads the requested
number of bytes or raises an exception if there isn't enough data
: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 = yield from read_exact(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
try:
opcode = Opcode(head1 & 0b00001111)
except ValueError as exc:
raise ProtocolError("invalid opcode") from exc
if (True if head2 & 0b10000000 else False) != mask:
raise ProtocolError("incorrect masking")
length = head2 & 0b01111111
if length == 126:
data = yield from read_exact(2)
(length,) = struct.unpack("!H", data)
elif length == 127:
data = yield from read_exact(8)
(length,) = struct.unpack("!Q", data)
if max_size is not None and length > max_size:
raise PayloadTooBig(f"over size limit ({length} > {max_size} bytes)")
if mask:
mask_bytes = yield from read_exact(4)
# Read the data.
data = yield from read_exact(length)
if mask:
data = apply_mask(data, mask_bytes)
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 serialize(
self,
*,
mask: bool,
extensions: Optional[Sequence["extensions.Extension"]] = None,
) -> bytes:
"""
Write a WebSocket frame.
:param frame: frame to write
: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
"""
self.check()
if extensions is None:
extensions = []
for extension in extensions:
self = extension.encode(self)
output = io.BytesIO()
# Prepare the header.
head1 = (
(0b10000000 if self.fin else 0)
| (0b01000000 if self.rsv1 else 0)
| (0b00100000 if self.rsv2 else 0)
| (0b00010000 if self.rsv3 else 0)
| self.opcode
)
head2 = 0b10000000 if mask else 0
length = len(self.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_bytes = secrets.token_bytes(4)
output.write(mask_bytes)
# Prepare the data.
if mask:
data = apply_mask(self.data, mask_bytes)
else:
data = self.data
output.write(data)
return output.getvalue()
def check(self) -> None:
"""
Check that reserved bits and opcode have acceptable values.
:raises ~websockets.exceptions.ProtocolError: if a reserved
bit or the opcode is invalid
"""
if self.rsv1 or self.rsv2 or self.rsv3:
raise ProtocolError("reserved bits must be 0")
if self.opcode in CTRL_OPCODES:
if len(self.data) > 125:
raise ProtocolError("control frame too long")
if not self.fin:
raise ProtocolError("fragmented control frame")
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, memoryview)):
return OP_BINARY, data
else:
raise TypeError("data must be bytes-like or str")
def prepare_ctrl(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, memoryview)):
return bytes(data)
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
from . import extensions # isort:skip # noqa
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/src/websockets/headers.py 0000644 0001751 0000171 00000035100 00000000000 020020 0 ustar 00runner docker """
:mod:`websockets.headers` provides parsers and serializers for HTTP headers
used in WebSocket handshake messages.
"""
import base64
import binascii
import re
from typing import Callable, List, Optional, Sequence, Tuple, TypeVar, cast
from .exceptions import InvalidHeaderFormat, InvalidHeaderValue
from .typing import (
ConnectionOption,
ExtensionHeader,
ExtensionName,
ExtensionParameter,
Subprotocol,
UpgradeProtocol,
)
__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")
# 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 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/src/websockets/http.py 0000644 0001751 0000171 00000002220 00000000000 017361 0 ustar 00runner docker import ipaddress
import sys
from .imports import lazy_import
from .version import version as websockets_version
# For backwards compatibility:
lazy_import(
globals(),
# Headers and MultipleValuesError used to be defined in this module.
aliases={
"Headers": ".datastructures",
"MultipleValuesError": ".datastructures",
},
deprecated_aliases={
"read_request": ".legacy.http",
"read_response": ".legacy.http",
},
)
__all__ = ["USER_AGENT", "build_host"]
PYTHON_VERSION = "{}.{}".format(*sys.version_info)
USER_AGENT = f"Python/{PYTHON_VERSION} websockets/{websockets_version}"
def build_host(host: str, port: int, secure: bool) -> str:
"""
Build a ``Host`` header.
"""
# https://tools.ietf.org/html/rfc3986#section-3.2.2
# IPv6 addresses must be enclosed in brackets.
try:
address = ipaddress.ip_address(host)
except ValueError:
# host is a hostname
pass
else:
# host is an IP address
if address.version == 6:
host = f"[{host}]"
if port != (443 if secure else 80):
host = f"{host}:{port}"
return host
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/src/websockets/http11.py 0000644 0001751 0000171 00000024700 00000000000 017532 0 ustar 00runner docker import re
from typing import Callable, Generator, NamedTuple, Optional
from .datastructures import Headers
from .exceptions import SecurityError
MAX_HEADERS = 256
MAX_LINE = 4110
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]*")
# Consider converting to dataclasses when dropping support for Python < 3.7.
class Request(NamedTuple):
"""
WebSocket handshake request.
:param path: path and optional query
:param headers:
"""
path: str
headers: Headers
# body isn't useful is the context of this library
@classmethod
def parse(
cls, read_line: Callable[[], Generator[None, None, bytes]]
) -> Generator[None, None, "Request"]:
"""
Parse 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:`parse_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 read_line: generator-based coroutine that reads a LF-terminated
line or raises an exception if there isn't enough data
: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 = yield from parse_line(read_line)
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 = yield from parse_headers(read_line)
return cls(path, headers)
def serialize(self) -> bytes:
"""
Serialize an HTTP/1.1 GET request.
"""
# Since the path and headers only contain ASCII characters,
# we can keep this simple.
request = f"GET {self.path} HTTP/1.1\r\n".encode()
request += self.headers.serialize()
return request
# Consider converting to dataclasses when dropping support for Python < 3.7.
class Response(NamedTuple):
"""
WebSocket handshake response.
"""
status_code: int
reason_phrase: str
headers: Headers
body: Optional[bytes] = None
# If processing the response triggers an exception, it's stored here.
exception: Optional[Exception] = None
@classmethod
def parse(
cls,
read_line: Callable[[], Generator[None, None, bytes]],
read_exact: Callable[[int], Generator[None, None, bytes]],
read_to_eof: Callable[[], Generator[None, None, bytes]],
) -> Generator[None, None, "Response"]:
"""
Parse 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:`parse_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 read_line: generator-based coroutine that reads a LF-terminated
line or raises an exception if there isn't enough data
:param read_exact: generator-based coroutine that reads the requested
number of bytes or raises an exception if there isn't enough data
:raises EOFError: if the connection is closed without a full HTTP response
:raises SecurityError: if the response exceeds a security limit
:raises LookupError: if the response isn't well formatted
:raises ValueError: if the response isn't well formatted
"""
# https://tools.ietf.org/html/rfc7230#section-3.1.2
# As in parse_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 = yield from parse_line(read_line)
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 = yield from parse_headers(read_line)
# https://tools.ietf.org/html/rfc7230#section-3.3.3
if "Transfer-Encoding" in headers:
raise NotImplementedError("transfer codings aren't supported")
# Since websockets only does GET requests (no HEAD, no CONNECT), all
# responses except 1xx, 204, and 304 include a message body.
if 100 <= status_code < 200 or status_code == 204 or status_code == 304:
body = None
else:
content_length: Optional[int]
try:
# MultipleValuesError is sufficiently unlikely that we don't
# attempt to handle it. Instead we document that its parent
# class, LookupError, may be raised.
raw_content_length = headers["Content-Length"]
except KeyError:
content_length = None
else:
content_length = int(raw_content_length)
if content_length is None:
body = yield from read_to_eof()
else:
body = yield from read_exact(content_length)
return cls(status_code, reason, headers, body)
def serialize(self) -> bytes:
"""
Serialize an HTTP/1.1 GET response.
"""
# Since the status line and headers only contain ASCII characters,
# we can keep this simple.
response = f"HTTP/1.1 {self.status_code} {self.reason_phrase}\r\n".encode()
response += self.headers.serialize()
if self.body is not None:
response += self.body
return response
def parse_headers(
read_line: Callable[[], Generator[None, None, bytes]]
) -> Generator[None, None, Headers]:
"""
Parse HTTP headers.
Non-ASCII characters are represented with surrogate escapes.
:param read_line: generator-based coroutine that reads a LF-terminated
line or raises an exception if there isn't enough data
"""
# 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 = yield from parse_line(read_line)
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 SecurityError("too many HTTP headers")
return headers
def parse_line(
read_line: Callable[[], Generator[None, None, bytes]]
) -> Generator[None, None, bytes]:
"""
Parse a single line.
CRLF is stripped from the return value.
:param read_line: generator-based coroutine that reads a LF-terminated
line or raises an exception if there isn't enough data
"""
# Security: TODO: add a limit here
line = yield from read_line()
# Security: this guarantees header values are small (hard-coded = 4 KiB)
if len(line) > MAX_LINE:
raise 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]
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/src/websockets/imports.py 0000644 0001751 0000171 00000006231 00000000000 020105 0 ustar 00runner docker import sys
import warnings
from typing import Any, Dict, Iterable, Optional
__all__ = ["lazy_import"]
def import_name(name: str, source: str, namespace: Dict[str, Any]) -> Any:
"""
Import from in .
There are two cases:
- is an object defined in
- is a submodule of source
Neither __import__ nor importlib.import_module does exactly this.
__import__ is closer to the intended behavior.
"""
level = 0
while source[level] == ".":
level += 1
assert level < len(source), "importing from parent isn't supported"
module = __import__(source[level:], namespace, None, [name], level)
return getattr(module, name)
def lazy_import(
namespace: Dict[str, Any],
aliases: Optional[Dict[str, str]] = None,
deprecated_aliases: Optional[Dict[str, str]] = None,
) -> None:
"""
Provide lazy, module-level imports.
Typical use::
__getattr__, __dir__ = lazy_import(
globals(),
aliases={
"": "",
...
},
deprecated_aliases={
...,
}
)
This function defines __getattr__ and __dir__ per PEP 562.
On Python 3.6 and earlier, it falls back to non-lazy imports and doesn't
raise deprecation warnings.
"""
if aliases is None:
aliases = {}
if deprecated_aliases is None:
deprecated_aliases = {}
namespace_set = set(namespace)
aliases_set = set(aliases)
deprecated_aliases_set = set(deprecated_aliases)
assert not namespace_set & aliases_set, "namespace conflict"
assert not namespace_set & deprecated_aliases_set, "namespace conflict"
assert not aliases_set & deprecated_aliases_set, "namespace conflict"
package = namespace["__name__"]
if sys.version_info[:2] >= (3, 7):
def __getattr__(name: str) -> Any:
assert aliases is not None # mypy cannot figure this out
try:
source = aliases[name]
except KeyError:
pass
else:
return import_name(name, source, namespace)
assert deprecated_aliases is not None # mypy cannot figure this out
try:
source = deprecated_aliases[name]
except KeyError:
pass
else:
warnings.warn(
f"{package}.{name} is deprecated",
DeprecationWarning,
stacklevel=2,
)
return import_name(name, source, namespace)
raise AttributeError(f"module {package!r} has no attribute {name!r}")
namespace["__getattr__"] = __getattr__
def __dir__() -> Iterable[str]:
return sorted(namespace_set | aliases_set | deprecated_aliases_set)
namespace["__dir__"] = __dir__
else: # pragma: no cover
for name, source in aliases.items():
namespace[name] = import_name(name, source, namespace)
for name, source in deprecated_aliases.items():
namespace[name] = import_name(name, source, namespace)
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1622143564.0407488
websockets-9.1/src/websockets/legacy/ 0000755 0001751 0000171 00000000000 00000000000 017300 5 ustar 00runner docker ././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/src/websockets/legacy/__init__.py 0000644 0001751 0000171 00000000000 00000000000 021377 0 ustar 00runner docker ././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/src/websockets/legacy/auth.py 0000644 0001751 0000171 00000012725 00000000000 020622 0 ustar 00runner docker """
:mod:`websockets.legacy.auth` provides HTTP Basic Authentication according to
:rfc:`7235` and :rfc:`7617`.
"""
import functools
import hmac
import http
from typing import Any, Awaitable, Callable, Iterable, Optional, Tuple, Union, cast
from ..datastructures import Headers
from ..exceptions import InvalidHeader
from ..headers import build_www_authenticate_basic, parse_authorization_basic
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.
"""
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: Optional[Callable[[Any], BasicAuthWebSocketServerProtocol]] = None,
) -> Callable[[Any], BasicAuthWebSocketServerProtocol]:
"""
Protocol factory that enforces HTTP Basic Auth.
``basic_auth_protocol_factory`` is designed to integrate with
:func:`~websockets.legacy.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):
credentials_list = [cast(Credentials, credentials)]
elif isinstance(credentials, Iterable):
credentials_list = list(credentials)
if not all(is_credentials(item) for item in credentials_list):
raise TypeError(f"invalid credentials argument: {credentials}")
else:
raise TypeError(f"invalid credentials argument: {credentials}")
credentials_dict = dict(credentials_list)
async def check_credentials(username: str, password: str) -> bool:
try:
expected_password = credentials_dict[username]
except KeyError:
return False
return hmac.compare_digest(expected_password, password)
if create_protocol is None:
# Not sure why mypy cannot figure this out.
create_protocol = cast(
Callable[[Any], BasicAuthWebSocketServerProtocol],
BasicAuthWebSocketServerProtocol,
)
return functools.partial(
create_protocol,
realm=realm,
check_credentials=check_credentials,
)
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/src/websockets/legacy/client.py 0000644 0001751 0000171 00000062117 00000000000 021137 0 ustar 00runner docker """
:mod:`websockets.legacy.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, Callable, Generator, List, Optional, Sequence, Tuple, Type, cast
from ..datastructures import Headers, HeadersLike
from ..exceptions import (
InvalidHandshake,
InvalidHeader,
InvalidMessage,
InvalidStatusCode,
NegotiationError,
RedirectHandshake,
SecurityError,
)
from ..extensions.base import ClientExtensionFactory, Extension
from ..extensions.permessage_deflate import enable_client_permessage_deflate
from ..headers import (
build_authorization_basic,
build_extension,
build_subprotocol,
parse_extension,
parse_subprotocol,
)
from ..http import USER_AGENT, build_host
from ..typing import ExtensionHeader, Origin, Subprotocol
from ..uri import WebSocketURI, parse_uri
from .handshake import build_request, check_response
from .http import read_response
from .protocol import WebSocketCommonProtocol
__all__ = ["connect", "unix_connect", "WebSocketClientProtocol"]
logger = logging.getLogger("websockets.server")
class WebSocketClientProtocol(WebSocketCommonProtocol):
"""
:class:`~asyncio.Protocol` subclass implementing a WebSocket client.
:class:`WebSocketClientProtocol`:
* performs the opening handshake to establish the connection;
* provides :meth:`recv` and :meth:`send` coroutines for receiving and
sending messages;
* deals with control frames automatically;
* performs the closing handshake to terminate the connection.
:class:`WebSocketClientProtocol` 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 for completing
the closing handshake and terminating the TCP connection. For legacy
reasons, :meth:`close` completes in at most ``5 * close_timeout`` seconds.
``close_timeout`` needs to be a parameter of the protocol because
websockets usually calls :meth:`close` implicitly upon exit when
:func:`connect` is used as a context manager.
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 :mod:`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 attributes must be treated as read-only.
"""
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)
# Remove this branch when dropping support for Python < 3.8
# because CancelledError no longer inherits Exception.
except asyncio.CancelledError: # pragma: no cover
raise
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 several 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()
request_headers["Host"] = build_host(wsuri.host, wsuri.port, wsuri.secure)
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::
async with connect(...) as websocket:
...
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.
``create_protocol`` defaults to :class:`WebSocketClientProtocol`. It may
be replaced by a wrapper or a subclass to customize the protocol that
manages the connection.
The behavior of ``ping_interval``, ``ping_timeout``, ``close_timeout``,
``max_size``, ``max_queue``, ``read_limit``, and ``write_limit`` is
described in :class:`WebSocketClientProtocol`.
: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,
*,
create_protocol: Optional[Callable[[Any], WebSocketClientProtocol]] = None,
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,
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.
timeout: Optional[float] = kwargs.pop("timeout", None)
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.
klass: Optional[Type[WebSocketClientProtocol]] = kwargs.pop("klass", None)
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
# Backwards compatibility: recv() used to return None on closed connections
legacy_recv: bool = kwargs.pop("legacy_recv", False)
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":
extensions = enable_client_permessage_deflate(extensions)
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 kwargs.pop("unix", False):
path: Optional[str] = kwargs.pop("path", None)
create_connection = functools.partial(
loop.create_unix_connection, factory, path, **kwargs
)
else:
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
)
# 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.protocol.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.protocol = 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: Optional[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, unix=True, **kwargs)
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/src/websockets/legacy/framing.py 0000644 0001751 0000171 00000011020 00000000000 021267 0 ustar 00runner docker """
:mod:`websockets.legacy.framing` reads and writes WebSocket frames.
It deals with a single frame at a time. Anything that depends on the sequence
of frames is implemented in :mod:`websockets.legacy.protocol`.
See `section 5 of RFC 6455`_.
.. _section 5 of RFC 6455: http://tools.ietf.org/html/rfc6455#section-5
"""
import struct
from typing import Any, Awaitable, Callable, Optional, Sequence
from ..exceptions import PayloadTooBig, ProtocolError
from ..frames import Frame as NewFrame, Opcode
try:
from ..speedups import apply_mask
except ImportError: # pragma: no cover
from ..utils import apply_mask
class Frame(NewFrame):
@classmethod
async def read(
cls,
reader: Callable[[int], Awaitable[bytes]],
*,
mask: bool,
max_size: Optional[int] = None,
extensions: Optional[Sequence["extensions.Extension"]] = None,
) -> "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
try:
opcode = Opcode(head1 & 0b00001111)
except ValueError as exc:
raise ProtocolError("invalid opcode") from exc
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"over 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 = cls(*extension.decode(frame, max_size=max_size))
frame.check()
return frame
def write(
self,
write: Callable[[bytes], Any],
*,
mask: bool,
extensions: Optional[Sequence["extensions.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 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(self.serialize(mask=mask, extensions=extensions))
# Backwards compatibility with previously documented public APIs
from ..frames import parse_close # isort:skip # noqa
from ..frames import prepare_ctrl as encode_data # isort:skip # noqa
from ..frames import prepare_data # isort:skip # noqa
from ..frames import serialize_close # isort:skip # noqa
# at the bottom to allow circular import, because Extension depends on Frame
from .. import extensions # isort:skip # noqa
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/src/websockets/legacy/handshake.py 0000644 0001751 0000171 00000014121 00000000000 021577 0 ustar 00runner docker """
:mod:`websockets.legacy.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
from typing import List
from ..datastructures import Headers, MultipleValuesError
from ..exceptions import InvalidHeader, InvalidHeaderValue, InvalidUpgrade
from ..headers import parse_connection, parse_upgrade
from ..typing import ConnectionOption, UpgradeProtocol
from ..utils import accept_key as accept, generate_key
__all__ = ["build_request", "check_request", "build_response", "check_response"]
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`
"""
key = generate_key()
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. The RFC always uses "websocket", except
# in section 11.2. (IANA registration) where it uses "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 as exc:
raise InvalidHeader("Sec-WebSocket-Key") from exc
except MultipleValuesError as exc:
raise InvalidHeader(
"Sec-WebSocket-Key", "more than one Sec-WebSocket-Key header found"
) from exc
try:
raw_key = base64.b64decode(s_w_key.encode(), validate=True)
except binascii.Error as exc:
raise InvalidHeaderValue("Sec-WebSocket-Key", s_w_key) from exc
if len(raw_key) != 16:
raise InvalidHeaderValue("Sec-WebSocket-Key", s_w_key)
try:
s_w_version = headers["Sec-WebSocket-Version"]
except KeyError as exc:
raise InvalidHeader("Sec-WebSocket-Version") from exc
except MultipleValuesError as exc:
raise InvalidHeader(
"Sec-WebSocket-Version", "more than one Sec-WebSocket-Version header found"
) from exc
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. The RFC always uses "websocket", except
# in section 11.2. (IANA registration) where it uses "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 as exc:
raise InvalidHeader("Sec-WebSocket-Accept") from exc
except MultipleValuesError as exc:
raise InvalidHeader(
"Sec-WebSocket-Accept", "more than one Sec-WebSocket-Accept header found"
) from exc
if s_w_accept != accept(key):
raise InvalidHeaderValue("Sec-WebSocket-Accept", s_w_accept)
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/src/websockets/legacy/http.py 0000644 0001751 0000171 00000015266 00000000000 020643 0 ustar 00runner docker import asyncio
import re
from typing import Tuple
from ..datastructures import Headers
from ..exceptions import SecurityError
__all__ = ["read_request", "read_response"]
MAX_HEADERS = 256
MAX_LINE = 4110
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 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 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]
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/src/websockets/legacy/protocol.py 0000644 0001751 0000171 00000144731 00000000000 021525 0 ustar 00runner docker """
:mod:`websockets.legacy.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,
Mapping,
Optional,
Union,
cast,
)
from ..datastructures import Headers
from ..exceptions import (
ConnectionClosed,
ConnectionClosedError,
ConnectionClosedOK,
InvalidState,
PayloadTooBig,
ProtocolError,
)
from ..extensions.base import Extension
from ..frames import (
OP_BINARY,
OP_CLOSE,
OP_CONT,
OP_PING,
OP_PONG,
OP_TEXT,
Opcode,
parse_close,
prepare_ctrl,
prepare_data,
serialize_close,
)
from ..typing import Data, Subprotocol
from .framing import Frame
__all__ = ["WebSocketCommonProtocol"]
logger = logging.getLogger("websockets.protocol")
# 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.legacy.server.WebSocketServerProtocol` and
:class:`~websockets.legacy.client.WebSocketClientProtocol` implement the
opening handshake, which is different between servers and clients.
"""
# 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[Subprotocol] = 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 pong 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("don't use secure", DeprecationWarning)
return self._secure
# Public API
@property
def local_address(self) -> Any:
"""
Local address of the connection as a ``(host, port)`` tuple.
When the connection isn't open, ``local_address`` is ``None``.
"""
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 as a ``(host, port)`` tuple.
When the connection isn't open, ``remote_address`` is ``None``.
"""
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.
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.
:meth:`send` rejects dict-like objects because this is often an error.
If you wish to send the keys of a dict-like object as fragments, call
its :meth:`~dict.keys` method and pass the result to :meth:`send`.
Canceling :meth:`send` is discouraged. Instead, you should close the
connection with :meth:`close`. Indeed, there are only two situations
where :meth:`send` may yield 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 that yields control.
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)
# Catch a common mistake -- passing a dict to send().
elif isinstance(message, Mapping):
raise TypeError("data is a dict-like object")
# 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
# coverage reports this code as not covered, but it is
# exercised by tests - changing it breaks the tests!
async for message_chunk in aiter_message: # type: ignore # pragma: no cover # noqa
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` that will be completed when the
corresponding pong is received. You can ignore it if you don't intend
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 = prepare_ctrl(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 = prepare_ctrl(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, TimeoutError, 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;
# - TimeoutError if the TCP connection times out;
# - 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(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().
pong_waiter = await self.ping()
if self.ping_timeout is not None:
try:
await asyncio.wait_for(
pong_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
# Remove this branch when dropping support for Python < 3.8
# because CancelledError no longer inherits Exception.
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():
# Coverage marks this line as a partially executed branch.
# I supect a bug in coverage. Ignore it for now.
return # pragma: no cover
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():
# Coverage marks this line as a partially executed branch.
# I supect a bug in coverage. Ignore it for now.
return # pragma: no cover
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.
# Coverage marks this line as a partially executed branch.
# I supect a bug in coverage. Ignore it for now.
await self.wait_for_connection_lost() # pragma: no cover
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 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/src/websockets/legacy/server.py 0000644 0001751 0000171 00000124661 00000000000 021172 0 ustar 00runner docker """
:mod:`websockets.legacy.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 ..datastructures import Headers, HeadersLike, MultipleValuesError
from ..exceptions import (
AbortHandshake,
InvalidHandshake,
InvalidHeader,
InvalidMessage,
InvalidOrigin,
InvalidUpgrade,
NegotiationError,
)
from ..extensions.base import Extension, ServerExtensionFactory
from ..extensions.permessage_deflate import enable_server_permessage_deflate
from ..headers import build_extension, parse_extension, parse_subprotocol
from ..http import USER_AGENT
from ..typing import ExtensionHeader, Origin, Subprotocol
from .handshake import build_response, check_request
from .http import read_request
from .protocol import WebSocketCommonProtocol
__all__ = ["serve", "unix_serve", "WebSocketServerProtocol", "WebSocketServer"]
logger = logging.getLogger("websockets.server")
HeadersLikeOrCallable = Union[HeadersLike, Callable[[str, Headers], HeadersLike]]
HTTPResponse = Tuple[http.HTTPStatus, HeadersLike, bytes]
class WebSocketServerProtocol(WebSocketCommonProtocol):
"""
:class:`~asyncio.Protocol` subclass implementing a WebSocket server.
:class:`WebSocketServerProtocol`:
* performs the opening handshake to establish the connection;
* provides :meth:`recv` and :meth:`send` coroutines for receiving and
sending messages;
* deals with control frames automatically;
* performs the closing handshake to terminate the connection.
You may customize the opening handshake by subclassing
:class:`WebSocketServer` and overriding:
* :meth:`process_request` to intercept the client request before any
processing and, if appropriate, to abort the WebSocket request and
return a HTTP response instead;
* :meth:`select_subprotocol` to select a subprotocol, if the client and
the server have multiple subprotocols in common and the default logic
for choosing one isn't suitable (this is rarely needed).
:class:`WebSocketServerProtocol` 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 for completing
the closing handshake and terminating the TCP connection. For legacy
reasons, :meth:`close` completes in at most ``4 * close_timeout`` seconds.
``close_timeout`` needs to be a parameter of the protocol because
websockets usually calls :meth:`close` implicitly when the connection
handler terminates.
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 :mod:`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 attributes must be treated as read-only.
"""
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,
)
# Remove this branch when dropping support for Python < 3.8
# because CancelledError no longer inherits Exception.
except asyncio.CancelledError: # pragma: no cover
raise
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 asyncio.CancelledError: # pragma: no cover
raise
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(Optional[Origin], headers.get("Origin"))
except MultipleValuesError as exc:
raise InvalidHeader("Origin", "more than one Origin header found") from exc
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 several 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:`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(
[
asyncio.ensure_future(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:`~WebSocketServer.close` and
:meth:`~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::
stop = asyncio.Future() # set this future to exit the server
async with serve(...):
await stop
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`.
``ws_handler`` is the WebSocket handler. It must be a coroutine accepting
two arguments: the WebSocket connection, which is an instance of
:class:`WebSocketServerProtocol`, and the path of the request.
The ``host`` and ``port`` arguments, as well as unrecognized keyword
arguments, are passed to :meth:`~asyncio.loop.create_server`.
For example, you can set the ``ssl`` keyword argument to a
:class:`~ssl.SSLContext` to enable TLS.
``create_protocol`` defaults to :class:`WebSocketServerProtocol`. It may
be replaced by a wrapper or a subclass to customize the protocol that
manages the connection.
The behavior of ``ping_interval``, ``ping_timeout``, ``close_timeout``,
``max_size``, ``max_queue``, ``read_limit``, and ``write_limit`` is
described in :class:`WebSocketServerProtocol`.
: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`` in
the list 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,
*,
create_protocol: Optional[Callable[[Any], WebSocketServerProtocol]] = None,
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,
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.
timeout: Optional[float] = kwargs.pop("timeout", None)
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.
klass: Optional[Type[WebSocketServerProtocol]] = kwargs.pop("klass", None)
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
# Backwards compatibility: recv() used to return None on closed connections
legacy_recv: bool = kwargs.pop("legacy_recv", False)
if loop is None:
loop = asyncio.get_event_loop()
ws_server = WebSocketServer(loop)
secure = kwargs.get("ssl") is not None
if compression == "deflate":
extensions = enable_server_permessage_deflate(extensions)
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 kwargs.pop("unix", False):
path: Optional[str] = kwargs.pop("path", None)
# 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
)
else:
create_server = functools.partial(
loop.create_server, factory, host, port, **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: Optional[str] = None,
**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, unix=True, **kwargs)
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/src/websockets/py.typed 0000644 0001751 0000171 00000000000 00000000000 017521 0 ustar 00runner docker ././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/src/websockets/server.py 0000644 0001751 0000171 00000037100 00000000000 017715 0 ustar 00runner docker import base64
import binascii
import collections
import email.utils
import http
import logging
from typing import Callable, Generator, List, Optional, Sequence, Tuple, Union, cast
from .connection import CONNECTING, OPEN, SERVER, Connection
from .datastructures import Headers, HeadersLike, MultipleValuesError
from .exceptions import (
InvalidHandshake,
InvalidHeader,
InvalidHeaderValue,
InvalidOrigin,
InvalidUpgrade,
NegotiationError,
)
from .extensions.base import Extension, ServerExtensionFactory
from .headers import (
build_extension,
parse_connection,
parse_extension,
parse_subprotocol,
parse_upgrade,
)
from .http import USER_AGENT
from .http11 import Request, Response
from .typing import (
ConnectionOption,
ExtensionHeader,
Origin,
Subprotocol,
UpgradeProtocol,
)
from .utils import accept_key
# See #940 for why lazy_import isn't used here for backwards compatibility.
from .legacy.server import * # isort:skip # noqa
__all__ = ["ServerConnection"]
logger = logging.getLogger(__name__)
HeadersLikeOrCallable = Union[HeadersLike, Callable[[str, Headers], HeadersLike]]
class ServerConnection(Connection):
side = SERVER
def __init__(
self,
origins: Optional[Sequence[Optional[Origin]]] = None,
extensions: Optional[Sequence[ServerExtensionFactory]] = None,
subprotocols: Optional[Sequence[Subprotocol]] = None,
extra_headers: Optional[HeadersLikeOrCallable] = None,
max_size: Optional[int] = 2 ** 20,
):
super().__init__(side=SERVER, state=CONNECTING, max_size=max_size)
self.origins = origins
self.available_extensions = extensions
self.available_subprotocols = subprotocols
self.extra_headers = extra_headers
def accept(self, request: Request) -> Response:
"""
Create a WebSocket handshake response event to send to the client.
If the connection cannot be established, the response rejects the
connection, which may be unexpected.
"""
# TODO: when changing Request to a dataclass, set the exception
# attribute on the request rather than the Response, which will
# be semantically more correct.
try:
key, extensions_header, protocol_header = self.process_request(request)
except InvalidOrigin as exc:
logger.debug("Invalid origin", exc_info=True)
return self.reject(
http.HTTPStatus.FORBIDDEN,
f"Failed to open a WebSocket connection: {exc}.\n",
)._replace(exception=exc)
except InvalidUpgrade as exc:
logger.debug("Invalid upgrade", exc_info=True)
return self.reject(
http.HTTPStatus.UPGRADE_REQUIRED,
(
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"
),
headers=Headers([("Upgrade", "websocket")]),
)._replace(exception=exc)
except InvalidHandshake as exc:
logger.debug("Invalid handshake", exc_info=True)
return self.reject(
http.HTTPStatus.BAD_REQUEST,
f"Failed to open a WebSocket connection: {exc}.\n",
)._replace(exception=exc)
except Exception as exc:
logger.warning("Error in opening handshake", exc_info=True)
return self.reject(
http.HTTPStatus.INTERNAL_SERVER_ERROR,
(
"Failed to open a WebSocket connection.\n"
"See server log for more information.\n"
),
)._replace(exception=exc)
headers = Headers()
headers["Upgrade"] = "websocket"
headers["Connection"] = "Upgrade"
headers["Sec-WebSocket-Accept"] = accept_key(key)
if extensions_header is not None:
headers["Sec-WebSocket-Extensions"] = extensions_header
if protocol_header is not None:
headers["Sec-WebSocket-Protocol"] = protocol_header
extra_headers: Optional[HeadersLike]
if callable(self.extra_headers):
extra_headers = self.extra_headers(request.path, request.headers)
else:
extra_headers = self.extra_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:
headers[name] = value
headers.setdefault("Date", email.utils.formatdate(usegmt=True))
headers.setdefault("Server", USER_AGENT)
return Response(101, "Switching Protocols", headers)
def process_request(
self, request: Request
) -> Tuple[str, Optional[str], Optional[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 request: request
: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
"""
headers = request.headers
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) if connection else None
)
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. The RFC always uses "websocket", except
# in section 11.2. (IANA registration) where it uses "WebSocket".
if not (len(upgrade) == 1 and upgrade[0].lower() == "websocket"):
raise InvalidUpgrade("Upgrade", ", ".join(upgrade) if upgrade else None)
try:
key = headers["Sec-WebSocket-Key"]
except KeyError as exc:
raise InvalidHeader("Sec-WebSocket-Key") from exc
except MultipleValuesError as exc:
raise InvalidHeader(
"Sec-WebSocket-Key", "more than one Sec-WebSocket-Key header found"
) from exc
try:
raw_key = base64.b64decode(key.encode(), validate=True)
except binascii.Error as exc:
raise InvalidHeaderValue("Sec-WebSocket-Key", key) from exc
if len(raw_key) != 16:
raise InvalidHeaderValue("Sec-WebSocket-Key", key)
try:
version = headers["Sec-WebSocket-Version"]
except KeyError as exc:
raise InvalidHeader("Sec-WebSocket-Version") from exc
except MultipleValuesError as exc:
raise InvalidHeader(
"Sec-WebSocket-Version",
"more than one Sec-WebSocket-Version header found",
) from exc
if version != "13":
raise InvalidHeaderValue("Sec-WebSocket-Version", version)
self.origin = self.process_origin(headers)
extensions_header, self.extensions = self.process_extensions(headers)
protocol_header = self.subprotocol = self.process_subprotocol(headers)
return key, extensions_header, protocol_header
def process_origin(self, headers: Headers) -> Optional[Origin]:
"""
Handle the Origin HTTP request header.
:param headers: request headers
: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(Optional[Origin], headers.get("Origin"))
except MultipleValuesError as exc:
raise InvalidHeader("Origin", "more than one Origin header found") from exc
if self.origins is not None:
if origin not in self.origins:
raise InvalidOrigin(origin)
return origin
def process_extensions(
self,
headers: Headers,
) -> 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 several 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
: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 self.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 self.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
def process_subprotocol(self, headers: Headers) -> 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
: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 self.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, self.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 common 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.
:param client_subprotocols: list of subprotocols offered by the client
:param server_subprotocols: list of subprotocols available on the server
"""
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]
def reject(
self,
status: http.HTTPStatus,
text: str,
headers: Optional[Headers] = None,
exception: Optional[Exception] = None,
) -> Response:
"""
Create a HTTP response event to send to the client.
A short plain text response is the best fallback when failing to
establish a WebSocket connection.
"""
body = text.encode()
if headers is None:
headers = Headers()
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; charset=utf-8")
headers.setdefault("Connection", "close")
return Response(status.value, status.phrase, headers, body)
def send_response(self, response: Response) -> None:
"""
Send a WebSocket handshake response to the client.
"""
if response.status_code == 101:
self.set_state(OPEN)
logger.debug(
"%s > HTTP/1.1 %d %s",
self.side,
response.status_code,
response.reason_phrase,
)
logger.debug("%s > %r", self.side, response.headers)
if response.body is not None:
logger.debug("%s > body (%d bytes)", self.side, len(response.body))
self.writes.append(response.serialize())
def parse(self) -> Generator[None, None, None]:
request = yield from Request.parse(self.reader.read_line)
assert self.state == CONNECTING
self.events.append(request)
yield from super().parse()
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/src/websockets/speedups.c 0000644 0001751 0000171 00000012304 00000000000 020030 0 ustar 00runner docker /* 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, PyObject **tmp, char **buffer, Py_ssize_t *length)
{
// This supports bytes, bytearrays, and memoryview objects,
// which are common data structures for handling byte streams.
// websockets.framing.prepare_data() returns only these types.
// If *tmp isn't NULL, the caller gets a new reference.
if (PyBytes_Check(obj))
{
*tmp = NULL;
*buffer = PyBytes_AS_STRING(obj);
*length = PyBytes_GET_SIZE(obj);
}
else if (PyByteArray_Check(obj))
{
*tmp = NULL;
*buffer = PyByteArray_AS_STRING(obj);
*length = PyByteArray_GET_SIZE(obj);
}
else if (PyMemoryView_Check(obj))
{
*tmp = PyMemoryView_GetContiguous(obj, PyBUF_READ, 'C');
if (*tmp == NULL)
{
return -1;
}
Py_buffer *mv_buf;
mv_buf = PyMemoryView_GET_BUFFER(*tmp);
*buffer = mv_buf->buf;
*length = mv_buf->len;
}
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.
PyObject *input_tmp = NULL;
char *input;
Py_ssize_t input_len;
PyObject *mask_tmp = NULL;
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 = NULL;
char *output;
// Other variables.
Py_ssize_t i = 0;
// Parse inputs.
if (!PyArg_ParseTupleAndKeywords(
args, kwds, "OO", kwlist, &input_obj, &mask_obj))
{
goto exit;
}
if (_PyBytesLike_AsStringAndSize(input_obj, &input_tmp, &input, &input_len) == -1)
{
goto exit;
}
if (_PyBytesLike_AsStringAndSize(mask_obj, &mask_tmp, &mask, &mask_len) == -1)
{
goto exit;
}
if (mask_len != MASK_LEN)
{
PyErr_SetString(PyExc_ValueError, "mask must contain 4 bytes");
goto exit;
}
// Create output.
result = PyBytes_FromStringAndSize(NULL, input_len);
if (result == NULL)
{
goto exit;
}
// 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)];
}
exit:
Py_XDECREF(input_tmp);
Py_XDECREF(mask_tmp);
return result;
}
static PyMethodDef speedups_methods[] = {
{
"apply_mask",
(PyCFunction)apply_mask,
METH_VARARGS | METH_KEYWORDS,
"Apply masking to the data of a 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 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/src/websockets/streams.py 0000644 0001751 0000171 00000005674 00000000000 020100 0 ustar 00runner docker from typing import Generator
class StreamReader:
"""
Generator-based stream reader.
This class doesn't support concurrent calls to :meth:`read_line()`,
:meth:`read_exact()`, or :meth:`read_to_eof()`. Make sure calls are
serialized.
"""
def __init__(self) -> None:
self.buffer = bytearray()
self.eof = False
def read_line(self) -> Generator[None, None, bytes]:
"""
Read a LF-terminated line from the stream.
The return value includes the LF character.
This is a generator-based coroutine.
:raises EOFError: if the stream ends without a LF
"""
n = 0 # number of bytes to read
p = 0 # number of bytes without a newline
while True:
n = self.buffer.find(b"\n", p) + 1
if n > 0:
break
p = len(self.buffer)
if self.eof:
raise EOFError(f"stream ends after {p} bytes, before end of line")
yield
r = self.buffer[:n]
del self.buffer[:n]
return r
def read_exact(self, n: int) -> Generator[None, None, bytes]:
"""
Read ``n`` bytes from the stream.
This is a generator-based coroutine.
:raises EOFError: if the stream ends in less than ``n`` bytes
"""
assert n >= 0
while len(self.buffer) < n:
if self.eof:
p = len(self.buffer)
raise EOFError(f"stream ends after {p} bytes, expected {n} bytes")
yield
r = self.buffer[:n]
del self.buffer[:n]
return r
def read_to_eof(self) -> Generator[None, None, bytes]:
"""
Read all bytes from the stream.
This is a generator-based coroutine.
"""
while not self.eof:
yield
r = self.buffer[:]
del self.buffer[:]
return r
def at_eof(self) -> Generator[None, None, bool]:
"""
Tell whether the stream has ended and all data was read.
This is a generator-based coroutine.
"""
while True:
if self.buffer:
return False
if self.eof:
return True
# When all data was read but the stream hasn't ended, we can't
# tell if until either feed_data() or feed_eof() is called.
yield
def feed_data(self, data: bytes) -> None:
"""
Write ``data`` to the stream.
:meth:`feed_data()` cannot be called after :meth:`feed_eof()`.
:raises EOFError: if the stream has ended
"""
if self.eof:
raise EOFError("stream ended")
self.buffer += data
def feed_eof(self) -> None:
"""
End the stream.
:meth:`feed_eof()` must be called at must once.
:raises EOFError: if the stream has ended
"""
if self.eof:
raise EOFError("stream ended")
self.eof = True
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/src/websockets/typing.py 0000644 0001751 0000171 00000002744 00000000000 017727 0 ustar 00runner docker 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__
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__
except AttributeError: # pragma: no cover
pass
ExtensionHeader = Tuple[ExtensionName, List[ExtensionParameter]]
ExtensionHeader__doc__ = """Extension in a Sec-WebSocket-Extensions header"""
try:
ExtensionHeader.__doc__ = ExtensionHeader__doc__
except AttributeError: # pragma: no cover
pass
Subprotocol = NewType("Subprotocol", str)
Subprotocol.__doc__ = """Subprotocol value in a Sec-WebSocket-Protocol header"""
ConnectionOption = NewType("ConnectionOption", str)
ConnectionOption.__doc__ = """Connection option in a Connection header"""
UpgradeProtocol = NewType("UpgradeProtocol", str)
UpgradeProtocol.__doc__ = """Upgrade protocol in an Upgrade header"""
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/src/websockets/uri.py 0000644 0001751 0000171 00000005414 00000000000 017211 0 ustar 00runner docker """
: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__ = ""
# All characters from the gen-delims and sub-delims sets in RFC 3987.
DELIMS = ":/?#[]@!$&'()*+,;="
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)
try:
uri.encode("ascii")
except UnicodeEncodeError:
# Input contains non-ASCII characters.
# It must be an IRI. Convert it to a URI.
host = host.encode("idna").decode()
resource_name = urllib.parse.quote(resource_name, safe=DELIMS)
if user_info is not None:
user_info = (
urllib.parse.quote(user_info[0], safe=DELIMS),
urllib.parse.quote(user_info[1], safe=DELIMS),
)
return WebSocketURI(secure, host, port, resource_name, user_info)
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/src/websockets/utils.py 0000644 0001751 0000171 00000001640 00000000000 017547 0 ustar 00runner docker import base64
import hashlib
import itertools
import secrets
__all__ = ["accept_key", "apply_mask"]
GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
def generate_key() -> str:
"""
Generate a random key for the Sec-WebSocket-Key header.
"""
key = secrets.token_bytes(16)
return base64.b64encode(key).decode()
def accept_key(key: str) -> str:
"""
Compute the value of the Sec-WebSocket-Accept header.
:param key: value of the Sec-WebSocket-Key header
"""
sha1 = hashlib.sha1((key + GUID).encode()).digest()
return base64.b64encode(sha1).decode()
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 010213 x ustar 00 22 mtime=1622143561.0
websockets-9.1/src/websockets/version.py 0000644 0001751 0000171 00000000020 00000000000 020063 0 ustar 00runner docker version = "9.1"
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1622143564.0367486
websockets-9.1/src/websockets.egg-info/ 0000755 0001751 0000171 00000000000 00000000000 017526 5 ustar 00runner docker ././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143563.0
websockets-9.1/src/websockets.egg-info/PKG-INFO 0000644 0001751 0000171 00000016120 00000000000 020623 0 ustar 00runner docker Metadata-Version: 1.2
Name: websockets
Version: 9.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| |tests|
.. |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
.. |tests| image:: https://github.com/aaugustin/websockets/workflows/tests/badge.svg?branch=master
:target: https://github.com/aaugustin/websockets/actions?workflow=tests
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
Classifier: Programming Language :: Python :: 3.9
Requires-Python: >=3.6.1
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143564.0
websockets-9.1/src/websockets.egg-info/SOURCES.txt 0000644 0001751 0000171 00000002156 00000000000 021416 0 ustar 00runner docker 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/connection.py
src/websockets/datastructures.py
src/websockets/exceptions.py
src/websockets/frames.py
src/websockets/headers.py
src/websockets/http.py
src/websockets/http11.py
src/websockets/imports.py
src/websockets/py.typed
src/websockets/server.py
src/websockets/speedups.c
src/websockets/streams.py
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
src/websockets/legacy/__init__.py
src/websockets/legacy/auth.py
src/websockets/legacy/client.py
src/websockets/legacy/framing.py
src/websockets/legacy/handshake.py
src/websockets/legacy/http.py
src/websockets/legacy/protocol.py
src/websockets/legacy/server.py ././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143563.0
websockets-9.1/src/websockets.egg-info/dependency_links.txt 0000644 0001751 0000171 00000000001 00000000000 023574 0 ustar 00runner docker
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143563.0
websockets-9.1/src/websockets.egg-info/not-zip-safe 0000644 0001751 0000171 00000000001 00000000000 021754 0 ustar 00runner docker
././@PaxHeader 0000000 0000000 0000000 00000000026 00000000000 010213 x ustar 00 22 mtime=1622143563.0
websockets-9.1/src/websockets.egg-info/top_level.txt 0000644 0001751 0000171 00000000063 00000000000 022257 0 ustar 00runner docker websockets
websockets/extensions
websockets/legacy
