mollom.getServerList

mollom.getServerList
Required	Name	Type	Description
required	public_key	string	Site public key
required	time	string	Site server time in this format: yyyy-MM-dd'T'HH:mm:ss-.SSSZ
required	hash	string	HMAC-SHA1 digest
required	nonce	string	One time nonce
optional	ssl	boolean	Use SSL for all api calls
returns		array of strings	Array of servers that can be used

This remote procedure call obtains the list of valid Mollom servers, needed to initiate traffic with the Mollom servers. The order of the servers in the list is important. Always use the first server in the list, unless that server is unavailable. A server is unavailable on the return of a network error or an XML-RPC error other than 1000, 1100 or 1200 (see Section 6 and Figure 2).

It would be a waste of overhead to call mollom.getServerList before every Mollom API call or HTTP request. Clients should include code to cache the server list for an extended time using either a database- or file-cache. Clients can be designed to refresh the server list once every few days or weeks, but this is not necessary. Mollom will return the 1100 error code if it needs a client to update its cached server list.

Clients should also request a new server list if they don’t have one or if all of the listed servers fail. A new server list can be retrieved from any Mollom server, but when no servers are currently assigned or when they have all failed, themollom.getServerList call should be directed to either http://xmlrpc1.mollom.com,http://xmlrpc2.mollom.com or http://xmlrpc3.mollom.com. Figure 2 illustrates in more detail how this mechanism should be implemented.

In other words, before every remote procedure call, the client should execute something along the lines of the following code, taken from the Drupal 6 Mollom module available at http://mollom.com/download:


// Retrieve the list of Mollom servers from the database:
$servers = variable_get('mollom_servers', NULL);
if ($servers == NULL) {
// Initialize server list:
$servers = _mollom_retrieve_server_list();

// Store the list of servers in the database:
variable_set(`mollom_servers', $servers);
}


If the server list is not yet initialized, the client needs to retrieve a server list from mollom.com as shown in the subroutine inFigure 2:


function _mollom_retrieve_server_list() {
// Start from a hard coded list of servers:
$servers = array('http://xmlrpc1.mollom.com',
'http://xmlrpc2.mollom.com',
'http://xmlrpc3.mollom.com');

// Retrieve the actual server list from mollom.com:
foreach ($servers as $server) {
$result = xmlrpc($server .'/'. MOLLOM_API_VERSION, `mollom.getServerList',
_mollom_authentication());
if (!xmlrpc_errno()) {
return $result;
}
}

return array();
}


Once the client has a valid list of Mollom servers, it can execute the actual remote procedure call as follows:


if (is_array($servers)) {
// Send the request to the first server, if that fails, try the
// other servers in the list:
foreach ($servers as $server) {
$result = xmlrpc($server . '/1.0', $method, $data + _mollom_authentication());
if ($errno = xmlrpc_errno()) {
if ($errno == MOLLOM_REFRESH) {
// Retrieve new server list from current server:
$servers = _mollom_retrieve_server_list();

// Store the updated list of servers in the database:
variable_set('mollom_servers', $servers);
}
else if ($errno == MOLLOM_ERROR) {
return $result;
}
else if ($errno == MOLLOM_REDIRECT) {
// Do nothing, we select the next server automatically.
}
}
else {
return $result;
}
}
}

// If everything fails, we reset the server list to force loading of a new list:
variable_set('mollom_servers', array());


Mollom Premium users can set the ssl parameter to true. This will supply a list of servers that are capable of accepting secured connections. All api calls to those servers can be routed over secure connections. The ssl parameter will be ignored for Mollom Free and Mollom Plus users.