Timeouts when using external resources

Scope: managed applications, ordinary applications.

1. When external resources are used through WSDefinitions, WSProxy, HTTPConnection, FTPConnection, and InternetMailProfile, set a timeout that is a maximum time period to wait for the operation execution. Otherwise, the application hangs or some of its functionality becomes unavailable.

Timeout protects applications from a variety of external factors:

  • Unstable Internet connection when a signal is continuously lost and the system is unable to get an uninterrupted server response.
  • Running anti-virus software or invalid firewall settings.
  • Invalid proxy server settings.
  • Unreliable web server performance due to a higher load or incorrect script execution.

For example, when you get web service details or call its operations and there is no response from the remote endpoint for a long time (for example, it is disabled or is undergoing maintenance, or there are temporary issues), you can endlessly wait for a response. Thus, if a web service is called as a result of interactive user operations, it will look like the application hangs. If a web service is called from a scheduled job, the related application functionality might become unavailable.

2. Generally, time required to execute an operation with external resources consists of six steps:

  • DNS Lookup is time spent to identify an IP address by a domain name (if applicable).
  • Connect is time required to connect to a web server using the received IP address.
  • Send is time required to send data to a web server.
  • Wait is time required to receive and process data by a web server.
  • Receive is time required to get a response from a web server.
  • Cache Read is time required to get data from a web server.

For example, if timeout is set to 60 seconds, the application and an external resource being called must complete all the six steps. Otherwise, the connection is closed and data transfer is suspended. If any operation fails, the system or user waits for 60 seconds for no reason.

We recommend that you set the timeout duration depending on the expected time of operation execution:

  • For quick operations (for example, server availability check), a timeout must be short.
  • Generally, avoid setting a timeout that exceeds 3 minutes. Otherwise, if the remote endpoint is not reachable, the application hangs.
  • If an operation is executed for a long time due to Send or Cache Read steps and large data size is transferred to a web server or a large file is imported from an external resource, set an increased timeout depending on the data size, the maximum timeout is 12 hours.

For more information on recommended timeouts for various operations, see clause 4 in the table.

3. Recommendations for reducing timeout duration and making applications more responsive when external recourses are used.

3.1. If you develop web services with operations whose timeout exceeds 20 seconds, we recommend that you:

  • Provide a separate Ping test operation in a web service.
  • For this web service, get a proxy server with a short timeout (7 seconds) in advance and call the Ping test operation.
  • After that get a main proxy server.

Web service call example.

Incorrect:

Correct:

PingPong web service module implementation:

Function Pong(Val Parameter)
  Return StringFunctionsClientServer.SubstituteParametersToString(NStr("en = "Hello %1"), Parameter);
EndFunction

Function Ping()
  Return True; // Connection test
EndFunction

Function Pong(Val Parameter)
  Return StringFunctionsClientServer.SubstituteParametersToString(NStr("en = "Hello %1"), Parameter);
EndFunction

Implementation of the calling side (Standard Subsystems Library is not used):

// Waiting for 1 minute maximum
PingPong = New WSProxy(WebServiceAddress, , , , , 60);
Result = PingPong.Pong(NStr("en = "Ball"));

// Waiting for 3 seconds maximum
PingPong = New WSProxy(WebServiceAddress, , , , , 3);
PingPong.Ping(); // Connection test

// Service is operating, waiting for 1 minute maximum
PingPong = New WSProxy(WebServiceAddress, , , , , 60); 
Result = PingPong.Pong(NStr("en = "Ball"));

If Standard Subsystems Library is used:

  • For web services, use the WSProxy function of the Common module (it supports the Ping test operation).
  • To get data over HTTP(S) and FTP(S), use the "Network download" subsystem.

An example of implementation of the calling side using the Standard Subsystems Library:

// Making Ping check call and waiting for 1 minute maximum when further operations are executed.
PingPong = Common.WSProxy(WebServiceAddress,..., 60, True);
// Service is definitely operating.
Result = PingPong.Pong(NStr("en = "Ball"));

3.2. For other types of external resources (other than web services), use the Ping operation alternatives. For example:

  • For services that work via REST API, send a test command. Generally, if you get a 200 response, it means that the service is operable.
  • For FTP/WebDAV resources, load (send) a dummy file to test.

3.3. Switch web services whose operations take much time due to the Wait stage (that is, the web application takes too long to process data) and cannot be accelerated or optimized for objective reasons to asynchronous mode:

  • Start a background job to execute this operation.
  • Provide additional operations to check whether the result can be received.

Example of asynchronous call of the web service.

Incorrect:

Correct:

Long web service module implementation:

Function GetData()
    Result = <time-consuming calculations>;
    Return Result;
EndFunction

Function StartDoLong()
    // Starting a background job
    OperationID = ...
    // Returning an operation ID to track its execution
    Return OperationID;
EndFunction

Function IsReady(Val OperationID)
    // Checking if the background job is completed by the passed ID
    Ready = ...
    Return Ready;
EndFunction

Function GetData(Val OperationID)
    Result = <Getting a ready-to-use result by the passed ID >;
    Return Result;
EndFunction

Calling side implementation:

Long = New WSProxy(WebServiceAddress, , , , , 600); // Waiting for 1 hour

Result = Long.GetData();

Long = New WSProxy(WebServiceAddress, , , , , 600); // Waiting for 1 hour

OperationID = Long.StartDoLong();

While Not Long.IsReady(OperationID) Do
    <Waiting for a particular time period>
EndDo;
Result = Long.GetData(OperationID);

* It is just a simplified calling side implementation scheme; in practice,
the calling side code must be also implemented asynchronously by enabling
a scheduled job or a periodic idle handler on the client
, which checks readiness and gets the result.

4. Recommended timeouts for operations:

Operation  Timeout, seconds
Get web service details  7
Check if the entered address is correct; interact with Service Manager in SaaS and other quick operations 10-20
Get counterparty details; exchange messages; text messaging; remote infobase administration in SaaS 60-1201
Send data exchange messages through a web service or get files from an external resource (max 1Mb). 120-1801
Import files (over 1Mb) If you know the file size, it is the size in Mb * 1282, otherwise it is the maximum load time up to 43,200 3

1 Call only after the Ping test operation.

2 It takes 128 seconds to load 1Mb at 64 Kbps as mobile operators sometimes limit the load speed to this value.

3 A timeout with a 43,200 seconds (12 hours) duration is a compromise solution, as in case of emergency, the process will become available and operable next morning, unlike an application that hangs when a timeout is not set.