Remote Timeouts

[#1]

Remote Timeouts

Some Notes:

Format

• Units: unit of measure for the timeout or limit (seconds, milliseconds, cycles, etc.)
• Description: describes the timeouts
• Outcome: describes the default behavior if a timeout or limit is reached.
• Related Timeouts: lists other timeouts that are closely related to the timeout in question, meaning they should be configured together because one timeout will affect another timeout

Notes

• This guide is heavily focused on the C SDK; certain timeouts may have different names in other SDK's or agents
• There are no descriptions of any imposed delays or timeouts related to thread pools on the ThingWorx Platform
• Local timeouts (not related to remote requests) were intentionally not added
• There are far too many applications to provide detail about every situation introduced by every timeout, but this should provide a good starting point for custom timeout configuration

Edge

---

socket_read_timeout

• Units: milliseconds
• Description: used to free the socket mutex allowing another service to read on the socket. Increasing this value is beneficial in low resource systems, but could lead to slower performance
• Outcome: socket read retry
• Related timeouts: ssl_read_timeout

ssl_read_timeout

• Units: milliseconds
• Description: If a partial record is read but not saved, it is possible to remove part of an ssl record that would have otherwise been essential in decrypting the entire record. This timeout is used to prevent this situation; it will allow a function to re-acquire the socket mutex in the event that a partial ssl record was captured but the socket_read_timeout was reached.
• Outcome: websocket read retry
• Related timeouts: socket_read_timeout

frame_read_timeout

• Units: milliseconds
• Description: essentially an idle socket timeout. If an edge device requests a message from the ThingWorx Platform, and nothing is read after the request for the time value specified in this property (not even request headers/ssl header), then the websocket is assumed to be experiencing an error and the connection is closed
• Outcome: websocket disconnect
• Related timeouts: message_timeout

message_timeout

• Units: milliseconds
• Description: the max overall message time that that the edge will wait for a full response during a particular request to the ThingWorx Platform. This timeout can be overridden by the frame read timeout if there is no activity on the socket for a given expected response period
• Outcome: websocket disconnect
• Related timeouts:frame_read_timeout, pingpong_timeout, Message Timeout (WSCommunication subsystem)

pingpong_timeout

• Units: milliseconds
• Description: the ping and pong messages are the heartbeat of the AlwaysOn protocol. If a pong is not received <pingpong_timeout> ms after the ping is sent, the websocket will disconnect even if there are successful messages during the ping/pong period. If a pong is received DURING the read loop of another service, the pongs will be routed to the pong manager and recorded to prevent a pong timeout
• Outcome: websocket disconnect
• Related timeouts: message_timeout

connect_timeout

• Units: milliseconds
• Description: when attempting to connect to the ThingWorx Platform, the connection and authentication will wait on an idle socket for the specified number of seconds before closing the connection and retrying
• Outcome: close socket and attempt to reconnect
• Related timeouts: connect_retries, Auth Message timeout (WSCommunication subsystem)

connect_retries

• Units: integer (number of tries, not actually a time measurement)
• Description: not actually coupled to an explicit time value. sets the max number of reconnect_timeouts that the edge will tolerate before giving up. In certain SDK's -1 will correspond to an infinite number of retries.
• Outcome: stop attempting to reconnect
• Related timeouts: connect_timeout, Auth Message timeout (WSCommunication subsystem)

file_xfer_timeout

• Units: milliseconds
• Description: If a file transfer to an edge device becomes idle for too long, this timeout will trigger an error and free the memory associated with the file in the program (this does not delete files on disk in case they are to be resumed later)
• Outcome: the file transfer is stopped, an error is reported, and associated file transfer memory objects are free'd
• Related timeouts: File Transfer Idle Timeout, Copy Timeout (Service)

ThingWorx Platform Related Services

• Units: milliseconds
• Description: some timeouts are passed in as a parameter to a service on an edge device (SendFile, twApi_InvokeService, etc.). These timeouts will act similarly to the WSCommunication message timeout, but they are driven from an edge device instead of the ThingWorx Platform.
• Outcome: timeout error reported
• Related timeouts: message_timeout, frame_read_timeout

Remote Thing (ThingWorx Platform)

---

Service Timeout

• Units: seconds
• Description: these timeouts are set explicitly in composer when editing remote services. These values will override the default message timeout that is set in the WSCommunication subsystem
• Outcome: service execution error
• Related timeouts: Property Timeout

Property Timeout

• Units: seconds
• Description: these timeouts are set explicitly in composer when editing remote properties. These values will override the default message timeout that is set in the WSCommunication subsystem.
• Outcome: property get/set error
• Related timeouts: Service Timeout

ThingWorx Platform Subsystems

---

WSCommunicationSubsystem

Idle Connection Timeout

• Units: seconds
• Description: if a particular websocket connection has not received or sent a message in the specified time, the connection is assumed to be invalid. The ThingWorx Platform will unbind any related things then disconnect the websocket. This should be set higher than the pingpong_timeout value
• Outcome: websocket disconnect
• Related timeouts: pingpong_timeout

Auth Message Timeout

• Units: seconds
• Description: when a websocket first connects (before binding) the connection will be allowed to stay open for the specified time interval without authenticating. Increasing this value will accommodate high latency devices, but the ThingWorx Platform will be more vulnerable to saturating its own connections with unauthorized websockets.
• Outcome: websocket disconnect
• Related timeouts: connect_timeout

Message Response Timeout

• Units: seconds
• Description: the max amount of time that is allowed during an edge request before claiming the service result as a failure
• Outcome: property get/set or service execution error
• Related timeouts: message_timeout (edge)

TunnelSubsystem

Startup Tunnel Timeout

• Units: seconds
• Description: once a remote tunnel is opened it will be given a specified time interval to establish an end-to-end connection before closing. For example, an SSH tunnel is opened but no client is attached to the endpoint
• Outcome: close tunnel, report error
• Related timeouts: n/a

Idle Tunnel Timeout

• Units: seconds
• Description: once a tunnel is established, and an end-to-end connection is established, this will monitor the activity on the socket and report a timeout if there is no read/write activity for the specified time interval
• Outcome: close tunnel, report error
• Related timeouts: n/a

FileTransferSubsystem

File Transfer Idle Timeout

• Units: seconds
• Description: when the file transfer subsystem Copy service is executed a series of secondary remote services will be executed to complete the transfer. The File Transfer Idle Timeout will monitor the activity of each secondary service and stop the entire Copy service if any one secondary service records no activity for the specified time interval.
• Outcome: transfer stopped, error reported
• Related timeouts: Copy Timeout (Service)

Copy (Service) Timeout

• Units: seconds
• Description: the number of seconds that the File Transfer Subsystem waits for the completion of a file transfer. This is set every time a transfer is executed.
• Outcome: transfer stopped, error reported
• Related timeouts: File Transfer Idle Timeout