How to write a custom resolution function-Enterprise Mobile Application Studio(EMAS)-阿里云帮助中心

This topic describes the input and response parameters for custom resolution functions and how to write one.

How custom resolution function policies work

The HTTPDNS process consists of several stages. Software-defined DNS (SDNS) lets you insert custom logic from Function Compute (FC) between these stages, enabling you to modify HTTPDNS behavior and implement custom features.

Runtime mechanism

The following table describes the capabilities of custom resolution functions at each stage.

Stage name	Description
BEFORE_READ_CACHE	1. Replace the domain name that is being resolved. 2. Replace the default cache key based on the context.
BEFORE_WRITE_CACHE	1. Before writing to the cache, modify the recursive resolution result. 2. Replace the default cache key based on the context.
BEFORE_WRITE_RESPONSE	Before returning the final response, modify the response content. This stage always runs, regardless of whether the cache is hit.

SDNS function inputs and outputs

HTTPDNS passes the runtime context as input to the Function Compute (FC) function, allowing you to define logic to process this data. The processed result is then merged back into the HTTPDNS resolution flow.

Input parameter format

HTTPDNS passes the runtime context to the event object of the Function Compute input parameter using a fixed JSON structure.

The fields are described as follows:

Field name	Subfield name	Meaning
domainName		The domain name that is being resolved.
clientIp		The public egress IP address of the client. This is referred to as the client IP address.
location	continent	The continent where the client IP address is located: africa: Africa asia: Asia north_america: North America south_america: South America europe: Europe oceania: Oceania antarctica: Antarctica
	region	The country or region code (ISO 3166-1 alpha-2) where the client IP address is located. The value is in lowercase. For more information, see Country or region codes.
	isp	The ISP line of the client IP address. This parameter is available only for client IP addresses in mainland China and includes five types: cmcc: China Mobile unicom: China Unicom chinanet: China Telecom bgp: Border Gateway Protocol (BGP) line unknown: Unknown line
	province	The province where the client IP address is located. This parameter is available only for client IP addresses in mainland China.
hookType		The current stage of the function. The stage names are as follows: BEFORE_READ_CACHE BEFORE_WRITE_CACHE BEFORE_WRITE_RESPONSE
ips[]		The list of IP addresses in the resolution result. This parameter is available only in the BEFORE_WRITE_CACHE and BEFORE_WRITE_RESPONSE stages.
ttl		The time-to-live (TTL) of the resolution result. This parameter is available only in the BEFORE_WRITE_CACHE and BEFORE_WRITE_RESPONSE stages.
parameters{}		The user-defined SDNS parameter object.
queryType		The resolution type. 1 indicates IPv4 resolution (A record), and 28 indicates IPv6 resolution (AAAA record).

Input parameter example

{
  "domainName": "www.aliyun.com", // The domain name that is being resolved
  "clientIp": "192.168.1.4", // Client IP address
  "location": {
    "continent": "asia", // The continent where the client IP address is located
    "region": "cn", // The country or region where the client IP address is located
    "isp": "bgp", // The ISP line of the client IP address 
    "province": "zhejiang" // The province where the client IP address is located
  },
  "ips": ["192.168.1.3"], // The list of IP addresses in the resolution result. This result is not available in the BEFORE_READ_CACHE stage.
  "ttl": 60, // The TTL of the resolution result. This result is not available in the BEFORE_READ_CACHE stage.
  "hookType": "BEFORE_WRITE_CACHE", // The stage where the function runs
  "parameters":{ // The parameter object carried in the resolution request
    "param1":"p1",   // Corresponds to the parameter "sdns-param1=p1" in the URL
    "param2":"p2"
   }
}

Note

The isp parameter has five values: cmcc, unicom, chinanet, bgp, and unknown. The code example uses bgp.
For client IP addresses in mainland China, the location field provides province-level geographic information. For client IP addresses outside mainland China, it provides only country- or region-level geographic information.
Custom HTTPDNS parameter names must use the "sdns-" prefix. HTTPDNS automatically removes this prefix when calling FC. If the prefix is missing, HTTPDNS ignores the parameter.

Response parameter format

The Function Compute function must return the processed result to HTTPDNS in the following format for parsing. All fields are optional. If a field is omitted or returned as null, HTTPDNS assumes the SDNS function does not need to modify that field.

Field name	Meaning
ips[]	The list of IP addresses in the resolution result.
ttl	The TTL of the resolution result in seconds. The value must be between 30 and 3600.
extra	Additional extension information to output to the client. The maximum length is 1024 characters.
domainName	Replaces the domain name that is being resolved. This parameter is valid only in the `BEFORE_READ_CACHE` stage.
cacheKey	Replaces the default cache key. The value must match the regular expression `[a-z0-9-]{1,32}`. This parameter is valid only in the This takes effect during the `BEFORE_READ_CACHE` and `BEFORE_WRITE_CACHE` stages.
hookResult	Specifies whether to return the result immediately after the hook function is executed: 0: Continue to the next stage. This is the default behavior. 1: Immediately return the result and do not proceed to the next stage. Only This applies to the `BEFORE_READ_CACHE` and `BEFORE_WRITE_CACHE` stages.

Response parameter example

{
    "ips": event.ips.concat(['192.168.1.2']),
    "ttl": event.ttl * 2,
    "extra": "some-thing-send-to-user"
    // ,"domainName": "www.alibabacloud.com" // Valid only in the BEFORE_READ_CACHE stage
    // ,"cacheKey": "cache-key-001" // Valid only in the BEFORE_READ_CACHE and BEFORE_WRITE_CACHE stages
 }

Function capabilities

During the resolution process, HTTPDNS executes the custom Function Compute (FC) logic at specified stages and provides the following capabilities:

Obtain the region and ISP information for the client IP address.
Modify the domain name resolution result and TTL.
Add custom data to be returned with the resolution result.

Function demo

This demo uses nodejs6 or nodejs8 as the programming language.

'use strict';
exports.handler = (event, context, callback) => {
  // Format the input parameter into an object
  const eventObj = JSON.parse(event.toString());
  const {
    location, // Region
    ips, // Resolution result returned by the authoritative DNS server
    ttl, // Original TTL
  } = eventObj;

  if (location.province === 'zhejiang' && location.isp === 'chinanet') {
    // When a user from Zhejiang Telecom accesses the domain name, return the specified IP address
    callback(null, {
      ips: ips.concat(['1.1.X.X']), // Add the specified IP address to the returned IP address array
      ttl: event.ttl * 2, // Modify the TTL
      extra: "", // Carry additional parameters for the client
    });
  } else {
    // Default response
    callback(null, {
      ips,
      ttl,
      extra: "",
    });
  }
};

For more information about how to create a function in Function Compute, see Configure custom resolution based on Function Compute.