Helper Objects

The Scriptable DNS comes with a list of helper objects to help with various tasks needed for dynamic routing. This page contains the documentation for the helper objects.

Monitoring

The monitoring helper allows you to check and monitor the uptime status of an IP. This is useful for uptime checking when returning DNS records. It takes a single IP parameter that is then monitored in the background.

The first time an IP is called, it is added into a background monitoring service while synchronously waiting for the initial latency. Once the IP is called again from the same server, the result is returned immediately.

Functions

Monitoring.getStatus(IP: string): MonitoringStatus

Returns the current status of the IP.

MonitoringStatus

The monitoring status object is returned by the Monitoring.getStatus helper and contains the monitoring information of a specific IP.

Field	Type	Description
isOnline	boolean	The current status of the IP (true: online, false: offline)
latency	integer	The last measured latency from the DNS server to this IP

/*
    Example usage for Monitoring.getStatus
    Returns the A record for 222.222.222.222 if the IP is online, otherwise return 111.111.111.111
*/
export default function handleQuery(query) {
  if (Monitoring.getStatus("222.222.222.222").isOnline == true) {
    return new ARecord("222.222.222.222", 30);
  }
  return new ARecord("111.111.111.111", 30);
}

GeoDatabase

GeoDatabase is a wrapper around a GeoDNS library. It allows you to easily look up the geo location of an IP address.

Functions

GeoDatabase.resolve(IP: string): GeoLocation

Returns the GeoLocation result for the specified IP based on a GeoDNS database.

/*
    Example usage for GeoDatabase.resolve
    Resolves the geo location for the IP 142.251.10.102 and returns the country code as a TXT record
*/
export default function handleQuery(query) {
  var location = GeoDatabase.resolve("142.251.10.102");
  return new TxtRecord(location.country, 30);
}

GeoDistance

GeoDistance contains helper methods to help you calculate the distance between two geographical points.

Functions

GeoDistance.calculate(lat1: double, lon1: double, lat2: double, lon2: double): double

Returns the geographical distance between two geographical locations based on latitude and longitude.

GeoDistance.calculate(loc1: GeoLocation, loc2: GeoLocation): double

Returns the geographical distance between two GeoLocation objects.

GeoDistance.calculate(server: Server, location: GeoLocation): double

Returns the geographical distance between a Server object and a GeoLocation object.

/*
    Example usage for GeoDistance.calculate
    Calculates the distance between two points on the map and returns them as a TxtRecord value
*/
export default function handleQuery(query) {
  var distance = GeoDistance.calculate(
    40.73061,
    -73.935242, // New York
    50.110924,
    8.682127, // Frankfurt
  );
  return new TxtRecord(
    "Distance between New York and Frankfurt: " + distance,
    30,
  );
}

RoutingEngine

RoutingEngine helps with dynamic geographic routing, weight calculation, and round robin logic based on a list of servers.

Functions

RoutingEngine.getWeightedRandom(servers: Array<Server>, onlineOnly: bool = false, applyWeight: bool = true): Server

Returns one server from an array of servers based on a round robin weighted random principle. Additionally, servers can be filtered by online servers only. To activate weights, the applyWeight parameter should be set to true.

/*
    Example usage for RoutingEngine.getWeightedRandom
    Returns one of the servers in a round robin fashion with the weights applied
*/
export default function handleQuery(query) {
  var servers = new Array(
    new Server("89.187.162.249", 40.69, -74.18, 100),
    new Server("89.187.162.249", 40.69, -74.18, 100),
    new Server("89.187.162.249", 40.69, -74.18, 75),
    new Server("89.187.162.249", 40.69, -74.18, 50),
  );

  return RoutingEngine.getWeightedRandom(
    servers,
    true, // Skip offline servers
  );
}

RoutingEngine.getClosestServer(servers: Array<Server>, location: GeoLocation, onlineOnly: bool = false, applyWeight: bool = true): Server

Returns one server from an array of servers based on a round robin weighted random principle that is closest to the given GeoLocation parameter.

Additionally, servers can be filtered by online servers only. To activate weights, the applyWeight parameter should be set to true.

/*
    Example usage for RoutingEngine.getClosestServer
    Returns the geographically closest server to the client that sent the query
*/
export default function handleQuery(query) {
  var servers = new Array(
    new Server("89.187.162.249", 40.69, -74.18),
    new Server("89.187.162.248", 52.31, 4.76),
    new Server("89.187.162.247", -37.67, 144.85),
    new Server("89.187.162.246", 33.94, -118.41),
  );

  return RoutingEngine.getClosestServer(
    servers,
    query.request.geoLocation,
    true, // Skip offline servers
  );
}

Server

The Server object is used to pass or return server information to various other helper methods and does not contain any functionality by itself.

Constructor

constructor(ip: string, latitude: double = 0, longitude: double = 0, weight: int = 100, online: bool = true)

Fields

Field	Type	Description
ip	string	The IP of the server
latitude	double	The geographical latitude of the server’s location
longitude	double	The geographical longitude of the server’s location
weight	int	The routing weight of the server in a weighted routing scenario