OctoPrintClient.socket
- OctoPrintClient.socket.options
The socket client’s options.
OctoPrintClient.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.OctoPrintClient.socket.options.rateSlidingWindowSize
Number of last rate measurements to take into account for timing analysis and communication throttling. See Communication Throttling below.
- OctoPrintClient.socket.connect(opts)
Connects the socket client to OctoPrint’s SockJS socket.
The optional parameter
opts
may be used to provide additional configuration options to the SockJS constructor. See the SockJS documentation on potential options.- Arguments
opts (
object()
) – Additional options for the SockJS constructor.
- OctoPrintClient.socket.reconnect()
Reconnects the socket client. If the socket is currently connected it will be disconnected first.
- OctoPrintClient.socket.disconnect()
Disconnects the socket client.
- OctoPrintClient.socket.onMessage(message, handler)
Registers the
handler
for messages of typemessage
.To register for all message types, provide
*
as the type to register for.handler
is expected to be a function accepting one object parametereventObj
, consisting of the received message as propertyevent
and the received payload (if any) as propertydata
.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 communication throttling needs to be adjusted or not.
Please refer to the Push API documentation for details on the possible message types and their payloads.
- Arguments
message (
string()
) – The type of message for which to registerhandler (
function()
) – The handler function
- OctoPrintClient.socket.removeMessage(message, handler)
Removes the
handler
for messages of typemessage
.const handler = (message) => { // do something with the message object }; OctoPrint.socket.onMessage("*", handler); // Use the same reference to the handler function to remove it again OctoPrint.socket.removeMessage("*", handler);
- Arguments
message (
string()
) – The type of message for which to remove the handlerhandler (
function()
) – The handler function
- OctoPrintClient.socket.sendMessage(type, payload)
Sends a message of type
type
with the providedpayload
to the server.Note that at the time of writing, OctoPrint only supports the
throttle
andauth
messages. See also the Push API documentation.- Arguments
type (
string()
) – Type of message to sendpayload (
object()
) – Payload to send
- OctoPrintClient.socket.sendAuth(userId, session)
Sends an
auth
message with the provideduserId
andsession
to the server.session
is expected to be thesession
value retrieved from any valid OctoPrint.browser.login(userId,…) response.See also the Push API documentation.
- Arguments
userId (
string()
) – An existing OctoPrint usernamesession (
string()
) – A valid session id for the provided username
- OctoPrintClient.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
OctoPrint.socket.increaseRate()
.- Arguments
measured (
Number()
) – Maximal measured message round trip timeminimum (
Number()
) – Lower round trip time limit for keeping the rate
- OctoPrintClient.socket.onRateTooHigh(measured, maximum)
Called by the socket client when the last measured round trip time was higher than the current upper processing 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
OctoPrint.socket.decreaseRate()
.- Arguments
measured (
Number()
) – Measured message round trip timeminimum (
Number()
) – Upper round trip time limit for keeping the rate
- OctoPrintClient.socket.increaseRate()
Instructs the server to increase the message rate by 500ms.
- OctoPrintClient.socket.decreaseRate()
Instructs the server to decrease the message rate by 500ms.
Sample to setup an authed socket
If you have a username and a password:
OctoPrint.socket.connect();
OctoPrint.browser.login("myusername", "mypassword", true)
.done(function(response) {
OctoPrint.socket.sendAuth("myusername", response.session);
});
If you have an API key:
var client = new OctoPrintClient({
baseurl: "http://example.com/",
apikey: "abcdef"
});
client.socket.connect();
client.browser.passiveLogin()
.done(function(response) {
client.socket.sendAuth(response.name, response.session);
});
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.