114 lines
4.8 KiB
ReStructuredText
114 lines
4.8 KiB
ReStructuredText
.. sec-jsclientlib-socket:
|
|
|
|
:mod:`OctoPrint.socket`
|
|
-----------------------
|
|
|
|
.. js:data:: OctoPrint.socket.options
|
|
|
|
The socket client's options.
|
|
|
|
``OctoPrint.socket.options.timeouts``
|
|
A list of consecutive timeouts after which to attempt reconnecting to a
|
|
disconnected sockets, in seconds. Defaults to ``[1, 1, 2, 3, 5, 8, 13, 20, 40, 100]``.
|
|
The default setting here makes the client slowly back off after the first couple of very
|
|
fast connection attempts don't succeed, and give up after 10 tries.
|
|
|
|
``OctoPrint.socket.options.rateSlidingWindowSize``
|
|
Number of last rate measurements to take into account for timing analysis and
|
|
communication throttling. See :ref:`Communication Throttling <sec-jsclient-socket-throttling>`
|
|
below.
|
|
|
|
.. js:function:: OctoPrint.socket.connect(opts)
|
|
|
|
Connects the socket client to OctoPrint's `SockJS <http://sockjs.org/>`_ socket.
|
|
|
|
The optional parameter ``opts`` may be used to provide additional configuration options
|
|
to the SockJS constructor. See the `SockJS documentation <https://github.com/sockjs/sockjs-client#sockjs-class>`_ on potential options.
|
|
|
|
:param object opts: Additional options for the SockJS constructor.
|
|
|
|
.. js:function:: OctoPrint.socket.reconnect()
|
|
|
|
Reconnects the socket client. If the socket is currently connected it will be disconnected first.
|
|
|
|
.. js:function:: OctoPrint.socket.disconnect()
|
|
|
|
Disconnects the socket client.
|
|
|
|
.. js:function:: OctoPrint.socket.onMessage(message, handler)
|
|
|
|
Registers the ``handler`` for messages of type ``message``.
|
|
|
|
To register for all message types, provide ``*`` as the type to register for.
|
|
|
|
``handler`` is expected to be a function accepting one object parameter ``eventObj``, consisting
|
|
of the received message as property ``key`` and the received payload (if any) as property ``data``.
|
|
|
|
.. code-block:: javascript
|
|
|
|
OctoPrint.socket.onMessage("*", function(message) {
|
|
// do something with the message object
|
|
});
|
|
|
|
The socket client will measure how long message processing over all handlers will take and utilize
|
|
that measurement to determine if the :ref:`communication throttling <sec-jsclient-socket-throttling>`
|
|
needs to be adjusted or not.
|
|
|
|
Please refer to the :ref:`Push API documentation <sec-api-push>`
|
|
for details on the possible message types and their payloads.
|
|
|
|
:param string message: The type of message for which to register
|
|
:param function handler: The handler function
|
|
|
|
.. js:function:: OctoPrint.socket.sendMessage(type, payload)
|
|
|
|
Sends a message of type ``type`` with the provided ``payload`` to the server.
|
|
|
|
Note that at the time of writing, OctoPrint only supports the ``throttle`` message. See
|
|
also the :ref:`Push API documentation <sec-api-push>`.
|
|
|
|
:param string type: Type of message to send
|
|
:param object payload: Payload to send
|
|
|
|
.. js:function:: OctoPrint.socket.onRateTooLow(measured, minimum)
|
|
|
|
Called by the socket client when the measured message round trip times have been lower than
|
|
the current lower processing limit over the full sliding window, indicating that messages
|
|
are now processed faster than the current rate and a faster rate might be possible.
|
|
|
|
Can be overwritten with custom handler methods. The default implementation will call
|
|
:js:func:`OctoPrint.socket.increaseRate`.
|
|
|
|
:param Number measured: Maximal measured message round trip time
|
|
:param Number minimum: Lower round trip time limit for keeping the rate
|
|
|
|
.. js:function:: OctoPrint.socket.onRateTooHigh(measured, maximum)
|
|
|
|
Called by the socket client when the last measured round trip time was higher than the
|
|
current upper procesisng limit, indicating that the messages are now processed slower than
|
|
the current rate requires and a slower rate might be necessary.
|
|
|
|
Can be overwritten with custom handler methods. The default implementation will call
|
|
:js:func:`OctoPrint.socket.decreaseRate`.
|
|
|
|
:param Number measured: Measured message round trip time
|
|
:param Number minimum: Upper round trip time limit for keeping the rate
|
|
|
|
.. js:function:: OctoPrint.socket.increaseRate()
|
|
|
|
Instructs the server to increase the message rate by 500ms.
|
|
|
|
.. js:function:: OctoPrint.socket.decreaseRate()
|
|
|
|
Instructs the server to decrease the message rate by 500ms.
|
|
|
|
.. sec-jsclient-socket-throttling:
|
|
|
|
Communication Throttling
|
|
========================
|
|
|
|
The socket client supports communication throttling. It will measure how long each incoming message takes
|
|
to be processed by all registered handlers. If the processing times in a sliding window are longer than
|
|
the current rate limit configured on the socket (default: 500ms between messages), the socket client will
|
|
instruct the server to send slower. If the messages are handled faster than half the current rate limit,
|
|
the socket client will instruct the server to send faster.
|