5io dZddlZddlmZddlZddlmZmZddlm Z m Z m Z ddl m Z ddlmZddlZddlmZmZmZmZmZGd d eZd Z e Gd d Ze GddZe GddZe GddZe GddZe GddZe GddZGddeZ GddeZ!dddddddddddd d e"d!ee#d"ed#ee d$ee d%ee d&eed'e$d(ee#d)eegdfd*eeegdfd+eeegdfd,eeegdfd-eeegdffd.Z%d/d0d e"d1e"d2efd3Z&y)4a WebSocket - `RFC 6455 `_ 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 `_, 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)ClientBootstrapTlsConnectionOptions SocketOptions) dataclass)IntEnum)CallableOptionalSequenceTupleUnionc:eZdZdZdZ dZ dZ dZ dZ dZ dZ y ) Opcodea>An opcode defines a frame's type. RFC 6455 classifies TEXT and BINARY as `data frames `_. A CONTINUATION frame "continues" the most recent data frame. All other opcodes are for `control frames `_. )r cx|jtjtjtjfvS)aRTrue 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. )valuerTEXTBINARY CONTINUATIONselfs r/home/marpiech/ifpan-abm-pgxpred/analysis/marpiech-gwas-test/venv/lib/python3.12/site-packages/awscrt/websocket.py is_data_framezOpcode.is_data_frames(zzfkk6==&:M:MNNNN) __name__ __module__ __qualname____doc__rrrCLOSEPINGPONGrr rrrgsQL D'F, E D D Or rlceZdZUdZdZeeed< dZeded< dZ ee ed< dZ ee e eefed< dZeed<y) OnConnectionSetupDataz1Data passed to the `on_connection_setup` callbackN exception WebSocket websockethandshake_response_statushandshake_response_headershandshake_response_body)r!r"r#r$r+r Exception__annotations__r-r.intr/r rstrr0bytesr(r rr*r*s};%)Ix ")1(,Ix $+04x}3GK%S/)B CJ&*U)r r*c&eZdZUdZdZeeed<y)OnConnectionShutdownDataz4Data passed to the `on_connection_shutdown` callbackNr+r!r"r#r$r+r r1r2r(r rr7r7s>%)Ix ")3r r7c<eZdZUdZeed< eed< eed< dZy) IncomingFramezRDescribes the frame you are receiving. Used in `on_incoming_frame` callbacks opcodepayload_lengthfinc6|jjS)aKTrue 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. )r;rrs rrzIncomingFrame.is_data_frames{{((**r N) r!r"r#r$rr2r3boolrr(r rr:r:s*. N1 Ih +r r:ceZdZUdZeed<y)OnIncomingFrameBeginDatazData 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)r!r"r#r$r:r2r(r rrArAs: :r rAc(eZdZUdZeed< eed<y)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. rBdataN)r!r"r#r$r:r2r5r(r rrDrD s  > K1r rDc2eZdZUdZeed< dZeeed<y)OnIncomingFrameCompleteDataz9Data passed to the `on_incoming_frame_complete` callback.rBNr+) r!r"r#r$r:r2r+r r1r(r rrGrG!s#C 5%)Ix ")Gr rGc&eZdZUdZdZeeed<y)OnSendFrameCompleteDatazIData passed to the :meth:`WebSocket.send_frame()` `on_complete` callback.Nr+r8r(r rrIrI-sS%)Ix ")Lr rIc ~eZdZdZfdZdZ dddddedeee e e e fd e d eeegdffd Zd efd ZxZS)r,z]A WebSocket connection. Use :meth:`connect()` to establish a new client connection. c0t|||_yN)super__init___binding)rbinding __class__s rrNzWebSocket.__init__?s  r cBtj|jy)aClose 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)_awscrtwebsocket_closerOrs rclosezWebSocket.closeDs  .r NT)r= on_completer;payloadr=rVclfd}tjjt||||y)aCSend a WebSocket frame asynchronously. See `RFC 6455 section 5 - Data Framing `_ 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 `_. `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 `_ 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:t}|r$tjj||_  |yy#t $rRt dtjtjtjjYywxYw)Nz6Exception in WebSocket.send_frame on_complete callbackfile) rIawscrt exceptions from_coder+ BaseExceptionprintsysstderr excepthookexc_inforU) error_codecbdatarVrs r _on_completez*WebSocket.send_frame.._on_complete~s{,.F#)#4#4#>#>z#J  *'+  NUXU_U_` /  s ?ABBN)rSwebsocket_send_framerOr)rr;rWr=rVrgs` ` r send_framezWebSocket.send_frameRs0X  $$ MM 6N     r sizecd|dkr tdtj|j|y)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 rz!Increment size cannot be negativeN) ValueErrorrSwebsocket_increment_read_windowrO)rrjs rincrement_read_windowzWebSocket.increment_read_windows+ !8@A A// tDr rL)r!r"r#r$rNrUrr rr4r5 bytearray memoryviewr?r rIrir3rn __classcell__rQs@rr,r,9s  /"GK? KO ??%UIz ABC?  ? h(?'@$'FGH ?B E# Er r,c<eZdZfdZdZdZdZdZdZxZ S)_WebSocketCorecht|||_||_||_||_||_yrL)rMrN_on_connection_setup_cb_on_connection_shutdown_cb_on_incoming_frame_begin_cb_on_incoming_frame_payload_cb_on_incoming_frame_complete_cb)ron_connection_setupon_connection_shutdownon_incoming_frame_beginon_incoming_frame_payloadon_incoming_frame_completerQs rrNz_WebSocketCore.__init__s8 ':$*@'+B(-F*.H+r ct}|r%tjj||_nt ||_||_||_||_ |j|y#t$rjtdtjtjtj |j |j j#YyYywxYw)Nz3Exception in WebSocket on_connection_setup callbackrZ)r*r\r]r^r+r,r-r.r/r0rvr_r`rarbrcrdrU)rrewebsocket_bindingr.r/r0rfs r_on_connection_setupz#_WebSocketCore._on_connection_setups'( %00:::FF ():;F +D(,F))@& )  ( ( 0 ) Gcjj Y NNCLLN ++  &&(, )sA**A.CCc>t}|r$tjj||_ |j |j |yy#t $rBtdtjtjtjYywxYw)Nz6Exception in WebSocket on_connection_shutdown callbackrZ) r7r\r]r^r+rwr_r`rarbrcrdrrerfs r_on_connection_shutdownz&_WebSocketCore._on_connection_shutdowns})+ %00:::FF  ,..://7; , JQTQ[Q[ \ NNCLLN + ,sAABBc<tt||||_t|j} |j|j |y#t $rBt dtjtjtjYywxYw)Nz7Exception in WebSocket on_incoming_frame_begin callbackrZFT) r:r_current_incoming_framerArxr_r`rarbrcrd)r opcode_intr<r=rfs r_on_incoming_frame_beginz'_WebSocketCore._on_incoming_frame_begins'4VJ5GY\']$)$*F*FG //;008    KRUR\R\ ] NNCLLN + sAABBct|j|} |j|j|y#t$rBt dt j t jt jYywxYw)Nz9Exception in WebSocket on_incoming_frame_payload callbackrZFT) rDrryr_r`rarbrcrd)rrErfs r_on_incoming_frame_payloadz)_WebSocketCore._on_incoming_frame_payloadsp+D,H,H$O 11=226:    MTWT^T^ _ NNCLLN + s6ABBcVt|j}|r$tjj ||_|` |j |j |y#t$rBtdtjtjtjYywxYw)Nz:Exception in WebSocket on_incoming_frame_complete callbackrZFT) rGrr\r]r^r+rzr_r`rarbrcrdrs r_on_incoming_frame_completez*_WebSocketCore._on_incoming_frame_completes,T-I-IJ %00:::FF   ( 22>33F;    NUXU_U_ ` NNCLLN + sAAB('B() r!r"r#rNrrrrrrqrrs@rrtrts" I)6 , r rtF) port bootstrapsocket_optionstls_connection_options proxy_optionsmanage_read_windowinitial_read_windowr|r}r~rhostrhandshake_requestrrrrrrr{r|r}r~rc |r | tdd}|dkr td|d}|tj}| t}t | | | | | }t j |||||||||| y)aAsynchronously 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: Upgrade: websocket Connection: Upgrade Sec-WebSocket-Key: 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 enabledrz('initial_read_window' cannot be negative)rlrget_or_create_static_defaultrrtrSwebsocket_client_connect)rrrrrrrrrr{r|r}r~rcores rconnectrsF  &cd dQCDD |#@@B & !"  $D $$    r /)pathrreturnc`tj||\}}tj||S)aCreate an HTTP request with all the required fields for a WebSocket handshake. The method will be "GET", and the following headers are added:: Host: Upgrade: websocket Connection: Upgrade Sec-WebSocket-Key: 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 "/". )rS"websocket_create_handshake_requestr_from_bindings)rrhttp_request_bindinghttp_headers_bindings rcreate_handshake_requestrs4"291[1[\`bf1g..  % %&:rs}Wv!5JJ! ==:OW:Oz(: ** *Z 33 3 ++ +8 ;; ; 22 2, GG G LL LgEgETj^j`+/.2=A04$)-SWTXX\Z^f f 3-f# f ( f ]+ f%%9:f,-ff"#f"#8"94"?@f%X/G.H$.N%OPf&h0H/I4/O&PQf (2L1Mt1S(TUf!)3N2OQU2U)V WfR8;RcRR{Rr