a

ů�i�o�@s�
dZd
dl
Z
d
dlmZ
d
dlZd
dlmZmZ
d
dlm	Z	m
Z
mZ
d
dlm
Z

d
dlmZ
d
dlZd
dlmZmZmZmZmZ
Gd	d
�d
e�ZdZe
Gdd
�d
��
Ze
Gdd�d��
Ze
Gdd�d��
Ze
Gdd�d��
Ze
Gdd�d��
Ze
Gdd�d��
Ze
Gdd�d��
ZGdd�de�Z Gdd�de�Z!dddddddddddd�e"ee#eee	eeee
eee$ee#eeg
dfeeeg
dfeeeg
dfeeeg
dfeeeg
dfd �d!d"�Z%d#d$�
e"e"ed%�d&d'�Z&dS)(a�
WebSocket - `RFC 6455 <https://www.rfc-editor.org/rfc/rfc6455>`_

Use the :func:`connect()` to establish a :class:`WebSocket` client connection.

Note from the developer: This is a very low-level API, which forces the
user to deal with things like data fragmentation.
A higher-level API could easily be built on top of this.

.. _authoring-callbacks:

Authoring Callbacks
-------------------
All network operations in `awscrt.websocket` are asynchronous.
Callbacks are always invoked on the WebSocket's networking thread.
You MUST NOT perform blocking network operations from any callback, or you will cause a deadlock.
For example: do not send a frame, and then wait for that frame to complete,
within a callback. The WebSocket cannot do work until your callback returns,
so the thread will be stuck. You can send the frame from within the callback,
just don't wait for it to complete within the callback.

If you want to do blocking waits, do it from a thread you control, like the main thread.
It's fine for the main thread to send a frame, and wait until it completes.

All functions and methods in `awscrt.websocket` are thread-safe.
They can be called from any mix of threads.

.. _flow-control-reading:

Flow Control (reading)
----------------------
By default, the WebSocket will read from the network as fast as it can hand you the data.
You must prevent the WebSocket from reading data faster than you can process it,
or memory usage could balloon until your application explodes.

There are two ways to manage this.

First, and simplest, is to process incoming data synchronously within the
`on_incoming_frame` callbacks. Since callbacks are invoked on the WebSocket's
networking thread, the WebSocket cannot read more data until the callback returns.
Therefore, processing the data in a synchronous manner
(i.e. writing to disk, printing to screen, etc) will naturally
affect `TCP flow control <https://en.wikipedia.org/wiki/Transmission_Control_Protocol#Flow_control>`_,
and prevent data from arriving too fast. However, you MUST NOT perform a blocking
network operation from within the callback or you risk deadlock (see :ref:`authoring-callbacks`).

The second, more complex, way requires you to manage the size of the read window.
Do this if you are processing the data asynchronously
(i.e. sending the data along on another network connection).
Create the WebSocket with `manage_read_window` set true,
and set `initial_read_window` to the number of bytes you are ready to receive right away.
Whenever the read window reaches 0, you will stop receiving anything.
The read window shrinks as you receive the payload from "data" frames (TEXT, BINARY, CONTINUATION).
Call :meth:`WebSocket.increment_read_window()` to increase the window again keep frames flowing in.
You only need to worry about the payload from "data" frames.
The WebSocket automatically increments its window to account for any
other incoming bytes, including other parts of a frame (opcode, payload-length, etc)
and the payload of other frame types (PING, PONG, CLOSE).
You'll probably want to do it like this:
Pick the max amount of memory to buffer, and set this as the `initial_read_window`.
When data arrives, the window has shrunk by that amount.
Send this data along on the other network connection.
When that data is done sending, call `increment_read_window()`
by the amount you just finished sending.
If you don't want to receive any data at first, set the `initial_read_window` to 0,
and `increment_read_window()` when you're ready.
Maintaining a larger window is better for overall throughput.

.. _flow-control-writing:

Flow Control (writing)
----------------------
You must also ensure that you do not continually send frames faster than the other
side can read them, or memory usage could balloon until your application explodes.

The simplest approach is to only send 1 frame at a time.
Use the :meth:`WebSocket.send_frame()` `on_complete` callback to know when the send is complete.
Then you can try and send another.

A more complex, but higher throughput, way is to let multiple frames be in flight
but have a cap. If the number of frames in flight, or bytes in flight, reaches
your cap then wait until some frames complete before trying to send more.

.. _api:

API
---
�N)
�NativeResource)�HttpProxyOptions�HttpRequest)�ClientBootstrap�TlsConnectionOptions�
SocketOptions)
�	dataclass)
�IntEnum)�Callable�Optional�Sequence�Tuple�Unionc@s0eZ
dZd
ZdZdZdZdZdZdZ	dd	�Z
d
S)�Opcodea>
An opcode defines a frame's type.

    RFC 6455 classifies TEXT and BINARY as `data frames <https://www.rfc-editor.org/rfc/rfc6455#section-5.6>`_.
    A CONTINUATION frame "continues" the most recent data frame.
    All other opcodes are for `control frames <https://www.rfc-editor.org/rfc/rfc6455#section-5.5>`_.
    )
r
�
���	�
c

Cs|jt
jt
jt
jfvS)
aR
True if this is a "data frame" opcode.

        TEXT, BINARY, and CONTINUATION are "data frames". The rest are "control" frames.

        If the WebSocket was created with `manage_read_window`,
        then the read window shrinks as "data frames" are received.
        See :ref:`flow-control-reading` for a thorough explanation.
        )�valuer�TEXT�BINARY�CONTINUATION�
�self�r�6/usr/lib64/python3.9/site-packages/awscrt/websocket.py�
is_data_frame�s	zOpcode.is_data_frameN)�__name__�
__module__�__qualname__�__doc__rrrZCLOSEZPINGZPONGrrrrrrgs
	rl����c@sjeZ
dZUd
ZdZeeed<dZeded<dZ	ee
ed<dZeee
eefed<dZeed<dS)	�OnConnectionSetupDataz1Data passed to the `on_connection_setup` callbackN�	exception�	WebSocket�	websocket�handshake_response_status�handshake_response_headers�handshake_response_body)rrr r!r#r�	Exception�__annotations__r%r&�intr'rr
�strr(�bytesrrrrr"�s
	
	
r"c@s"eZ
dZUd
ZdZeeed<dS)�OnConnectionShutdownDataz4Data passed to the `on_connection_shutdown` callbackNr#�rrr r!r#rr)r*rrrrr.�s

r.c@s2eZ
dZUd
Zeed<eed<eed<dd�ZdS)�
IncomingFramezRDescribes the frame you are receiving.

    Used in `on_incoming_frame` callbacks �opcode�payload_length�finc

Cs
|j�
�S)
aK
True if this is a "data frame".

        TEXT, BINARY, and CONTINUATION are "data frames". The rest are "control frames".

        If the WebSocket was created with `manage_read_window`,
        then the read window shrinks as "data frames" are received.
        See :ref:`flow-control-reading` for a thorough explanation.
        )r1rrrrrr�s	zIncomingFrame.is_data_frameN)	rrr r!rr*r+�boolrrrrrr0�s

r0c@seZ
dZUd
Zeed<dS)�OnIncomingFrameBeginDataz�Data passed to the `on_incoming_frame_begin` callback.

    Each `on_incoming_frame_begin` call will be followed by
    0+ `on_incoming_frame_payload` calls,
    followed by one `on_incoming_frame_complete` call.�frameN)rrr r!r0r*rrrrr5�s

r5c@s"eZ
dZUd
Zeed<eed<dS)�OnIncomingFramePayloadDataa8Data passed to the `on_incoming_frame_payload` callback.

    This callback will be invoked 0+ times.
    Each time, `data` will contain a bit more of the payload.
    Once all `frame.payload_length` bytes have been received
    (or the network connection is lost), the `on_incoming_frame_complete`
    callback will be invoked.

    If the WebSocket was created with `manage_read_window`,
    and this is a "data frame" (TEXT, BINARY, CONTINUATION),
    then the read window shrinks by `len(data)`.
    See :ref:`flow-control-reading` for a thorough explanation.
    r6�dataN)rrr r!r0r*r-rrrrr7

s

r7c@s*eZ
dZUd
Zeed<dZeeed<dS)�OnIncomingFrameCompleteDataz9Data passed to the `on_incoming_frame_complete` callback.r6Nr#)	rrr r!r0r*r#rr)rrrrr9!
s

r9c@s"eZ
dZUd
ZdZeeed<dS)�OnSendFrameCompleteDatazIData passed to the :meth:`WebSocket.send_frame()` `on_complete` callback.Nr#r/rrrrr:-
s

r:c	sreZ
dZd
Z�f
dd�Zdd�Zdddd�eeee	e
eefe
eeeg
dfd	�d
d�Zed�
d
d�Z�ZS)r$z]A WebSocket connection.

    Use :meth:`connect()` to establish a new client connection.
    cst��
�
|
|_dS�
N)�super�__init__�_binding)rZbinding�
�	__class__rrr=?
s

zWebSocket.__init__c

Cst�
|j�

d
S)a�
Close the WebSocket asynchronously.

        You should call this when you are done with a healthy WebSocket,
        to ensure that it shuts down and cleans up.
        You don't need to call this on a WebSocket that has already shut
        down, or is in the middle of shutting down, but it is safe to do so.
        This function is idempotent.

        To determine when shutdown has completed, you can use the
        `on_shutdown_complete` callback (passed into :meth:`connect()`).
        N)�_awscrtZwebsocket_closer>rrrr�closeD
szWebSocket.closeNT)r3�on_complete)r1�payloadr3rCcs*��
fd
d�}t�
�
jt|
�
|||�
dS)aCSend a WebSocket frame asynchronously.

        See `RFC 6455 section 5 - Data Framing <https://www.rfc-editor.org/rfc/rfc6455#section-5>`_
        for details on all frame types.

        This is a low-level API, which requires you to send the appropriate payload for each type of opcode.
        If you are not an expert, stick to sending :attr:`Opcode.TEXT` or :attr:`Opcode.BINARY` frames,
        and don't touch the FIN bit.

        See :ref:`flow-control-writing` to learn about limiting the amount of
        unsent data buffered in memory.

        Args:
            opcode: :class:`Opcode` for this frame.

            payload: Any `bytes-like object <https://docs.python.org/3/glossary.html#term-bytes-like-object>`_.
                `str` will always be encoded as UTF-8. It is fine to pass a `str` for a BINARY frame.
                None will result in an empty payload, the same as passing empty `bytes()`

            fin: The FIN bit indicates that this is the final fragment in a message.
                Do not set this False unless you understand
                `WebSocket fragmentation <https://www.rfc-editor.org/rfc/rfc6455#section-5.4>`_

            on_complete: Optional callback, invoked when the frame has finished sending.
                Takes a single :class:`OnSendFrameCompleteData` argument.

                If :attr:`OnSendFrameCompleteData.exception` is set, the connection
                was lost before this frame could be completely sent.

                But if `exception` is None, the frame was successfully written to the OS socket.
                (This doesn't mean the other endpoint has received the data yet,
                or even guarantee that the data has left the machine yet,
                but it's on track to get there).

                Be sure to read about :ref:`authoring-callbacks`.
        c
sht�}
|rt
j�|�
|
_z�du
r*�|
�

Wn6tyb


td
tjd�
tj	t�
��
�
��
Yn0dS)Nz6Exception in WebSocket.send_frame on_complete callback�
�file)r:�awscrt�
exceptions�	from_coder#�
BaseException�print�sys�stderr�
excepthook�exc_inforB)�
error_code�cbdata�rCrrr�_on_complete~
s








z*WebSocket.send_frame.<locals>._on_completeN)rAZwebsocket_send_framer>r)rr1rDr3rCrSrrRr�
send_frameR
s,




�zWebSocket.send_frame)
�sizecCs"|
d
krtd�
�
t
�|j|
�
dS)a`
Manually increment the read window by this many bytes, to continue receiving frames.

        See :ref:`flow-control-reading` for a thorough explanation.
        If the WebSocket was created without `manage_read_window`, this function does nothing.
        This function may be called from any thread.

        Args:
            size: in bytes
        r
z!Increment size cannot be negativeN)�
ValueErrorrAZwebsocket_increment_read_windowr>)rrUrrr�increment_read_window�
s

zWebSocket.increment_read_window)
N)rrr r!r=rBrrrr,r-�	bytearray�
memoryviewr4r
r:rTr+rW�
__classcell__rrr?rr$9
s
�
�

�Ar$csDeZ
dZ�f
d
d�Zdd�Zdd�Zdd�Zd	d
�Zdd�Z�Z	S)
�_WebSocketCorecs,t��
�
|
|_||_||_||_||_dSr;)r<r=�_on_connection_setup_cb�_on_connection_shutdown_cb�_on_incoming_frame_begin_cb�_on_incoming_frame_payload_cb�_on_incoming_frame_complete_cb)r�on_connection_setup�on_connection_shutdown�on_incoming_frame_begin�on_incoming_frame_payload�on_incoming_frame_completer?rrr=�
s





z_WebSocketCore.__init__cCs�t�}|
rt
j�|
�
|_n
t|�
|_||_||_||_	z|�
|�

WnBty�


td
t
jd�
t
jt
���
|jdu
r�|j��
Yn0dS)Nz3Exception in WebSocket on_connection_setup callbackrE)r"rGrHrIr#r$r%r&r'r(r\rJrKrLrMrNrOrB)rrPZwebsocket_bindingr&r'r(rQrrr�_on_connection_setup�
s











z#_WebSocketCore._on_connection_setupcCsdt�}|
rt
j�|
�
|_z|jdu
r.|�|�

Wn.ty^


td
tj	d�
tj
t���
Yn0dS)Nz6Exception in WebSocket on_connection_shutdown callbackrE)r.rGrHrIr#r]rJrKrLrMrNrO�rrPrQrrr�_on_connection_shutdown�
s








z&_WebSocketCore._on_connection_shutdowncCsjtt
|
�
||�|_t|j�
}z|jdu
r2|�|�

Wn0tyd


td
tjd�
tj	t�
��
YdS0dS)Nz7Exception in WebSocket on_incoming_frame_begin callbackrEFT)r0r�_current_incoming_framer5r^rJrKrLrMrNrO)rZ
opcode_intr2r3rQrrr�_on_incoming_frame_begin�
s








z'_WebSocketCore._on_incoming_frame_begincCsZt|j
|
�}z|jdu
r"|�|�

Wn0tyT


td
tjd�
tjt���
YdS0dS)Nz9Exception in WebSocket on_incoming_frame_payload callbackrEFT)	r7rir_rJrKrLrMrNrO)rr8rQrrr�_on_incoming_frame_payload�
s







z)_WebSocketCore._on_incoming_frame_payloadcCsnt|j
�
}|
rtj�|
�
|_|`
z|jdu
r6|�|�

Wn0tyh


td
t	j
d�
t	jt	���
YdS0dS)Nz:Exception in WebSocket on_incoming_frame_complete callbackrEFT)
r9rirGrHrIr#r`rJrKrLrMrNrOrgrrr�_on_incoming_frame_complete�
s










z*_WebSocketCore._on_incoming_frame_complete)
rrr r=rfrhrjrkrlrZrrr?rr[�
s

r[F)�port�	bootstrap�socket_options�tls_connection_options�
proxy_options�manage_read_window�initial_read_windowrbrcrdre)�hostrm�handshake_requestrnrorprqrrrsrarbrcrdrecCs�|r|d
urtd�
�
nd}|dkr*td�
�
|
d
ur6d}
|d
urFt
��}|d
urTt�}t|	|
|||
�}t�||
||||||||�

d
S)a�Asynchronously establish a client WebSocket connection.

    The `on_connection_setup` callback is invoked once the connection
    has succeeded or failed.

    If successful, a :class:`WebSocket` will be provided in the
    :class:`OnConnectionSetupData`. You should store this WebSocket somewhere,
    so that you can continue using it (the connection will shut down
    if the class is garbage collected).

    The WebSocket will shut down after one of these things occur:
        * You call :meth:`WebSocket.close()`
        * You, or the server, sends a CLOSE frame.
        * The underlying socket shuts down.
        * All references to the WebSocket are dropped,
          causing it to be garbage collected. However, you should NOT
          rely on this behavior. You should call :meth:`~WebSocket.close()` when you are
          done with a healthy WebSocket, to ensure that it shuts down and cleans up.
          It is very easy to accidentally keep a reference around without realizing it.

    Be sure to read about :ref:`authoring-callbacks`.

    Args:
        host: Hostname to connect to.

        port: Port to connect to. If not specified, it defaults to port 443
            when `tls_connection_options` is present, and port 80 otherwise.

        handshake_request: HTTP request for the initial WebSocket handshake.

            The request's method MUST be "GET", and the following headers are
            required::

                Host: <host>
                Upgrade: websocket
                Connection: Upgrade
                Sec-WebSocket-Key: <base64-encoding of 16 random bytes>
                Sec-WebSocket-Version: 13

            You can use :meth:`create_handshake_request()` to make a valid WebSocket
            handshake request, modifying the path and headers to fit your needs,
            and then passing it here.

        bootstrap: Client bootstrap to use when initiating socket connection.
            If not specified, the default singleton is used.

        socket_options: Socket options.
            If not specified, default options are used.

        proxy_options: HTTP Proxy options.
            If not specified, no proxy is used.

        manage_read_window: Set true to manually manage the flow-control read window.
            If false (the default), data arrives as fast as possible.
            See :ref:`flow-control-reading` for a thorough explanation.

        initial_read_window: The initial size of the read window, in bytes.
            This must be set if `manage_read_window` is true,
            otherwise it is ignored.
            See :ref:`flow-control-reading` for a thorough explanation.
            An initial size of 0 will prevent any frames from arriving
            until :meth:`WebSocket.increment_read_window()` is called.

        on_connection_setup: Callback invoked when the connect completes.
            Takes a single :class:`OnConnectionSetupData` argument.

            If successful, :attr:`OnConnectionSetupData.websocket` will be set.
            You should store the :class:`WebSocket` somewhere, so you can
            use it to send data when you're ready.
            The other callbacks will be invoked as events occur,
            until the final `on_connection_shutdown` callback.

            If unsuccessful, :attr:`OnConnectionSetupData.exception` will be set,
            and no further callbacks will be invoked.

            If this callback raises an exception, the connection will shut down.

        on_connection_shutdown: Optional callback, invoked when a connection shuts down.
            Takes a single :class:`OnConnectionShutdownData` argument.

            This callback is never invoked if `on_connection_setup` reported an exception.

        on_incoming_frame_begin: Optional callback, invoked once at the start of each incoming frame.
            Takes a single :class:`OnIncomingFrameBeginData` argument.

            Each `on_incoming_frame_begin` call will be followed by 0+
            `on_incoming_frame_payload` calls, followed by one
            `on_incoming_frame_complete` call.

            The "frame complete" callback is guaranteed to be invoked
            once for each "frame begin" callback, even if the connection
            is lost before the whole frame has been received.

            If this callback raises an exception, the connection will shut down.

        on_incoming_frame_payload: Optional callback, invoked 0+ times as payload data arrives.
            Takes a single :class:`OnIncomingFramePayloadData` argument.

            If `manage_read_window` is on, and this is a "data frame",
            then the read window shrinks accordingly.
            See :ref:`flow-control-reading` for a thorough explanation.

            If this callback raises an exception, the connection will shut down.

        on_incoming_frame_complete: Optional callback, invoked when the WebSocket
            is done processing an incoming frame.
            Takes a single :class:`OnIncomingFrameCompleteData` argument.

            If :attr:`OnIncomingFrameCompleteData.exception` is set,
            then something went wrong processing the frame
            or the connection was lost before the frame could be completed.

            If this callback raises an exception, the connection will shut down.
    NzD'initial_read_window' must be set if 'manage_read_window' is enabledr
z('initial_read_window' cannot be negative)rVrZget_or_create_static_defaultrr[rAZwebsocket_client_connect)rtrmrurnrorprqrrrsrarbrcrdreZcorerrr�connects@











�









�rv�
/)
�path)rtrx�returncCst�
||
�\}}t�||�S)
a�
Create an HTTP request with all the required fields for a WebSocket handshake.

    The method will be "GET", and the following headers are added::

        Host: <host>
        Upgrade: websocket
        Connection: Upgrade
        Sec-WebSocket-Key: <base64-encoding of 16 random bytes>
        Sec-WebSocket-Version: 13

    You may can add headers, or modify the path, before using this request.

    Args:
        host: Value for "Host" header
        path: Path (and query) string. Defaults to "/".
    )rAZ"websocket_create_handshake_requestrZ_from_bindings)rtrxZhttp_request_bindingZhttp_headers_bindingrrr�create_handshake_request�s
rz)'r!rArGrZawscrt.exceptionsZawscrt.httprrZ	awscrt.iorrrZdataclassesr�enumr	rL�typingr
rrr
rrZMAX_PAYLOAD_LENGTHr"r.r0r5r7r9r:r$r[r,r+r4rvrzrrrr�<module>
sp[







=
-






jp







�












�*