HTTPDNS:Basic configurations

Context configuration

The SDK uses HarmonyOS APIs for data storage and requires the Context parameter. You must set the Context parameter during configuration.

The following code provides an example:

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { httpdns } from '@aliyun/httpdns';

const ACCOUNT_ID = 'Replace this with the Account ID from the Alibaba Cloud HTTPDNS console'
        
export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // ************* Start of initialization configuration *************
    httpdns.configService(ACCOUNT_ID, {
      // Configure the Harmony context.
      context: this.context,
    });
    // ************* End of initialization configuration *************
  }
  // Other code is omitted.
}

Use HTTPS requests

You can specify whether the SDK uses HTTPS to send resolution requests to the server. By default, the SDK uses HTTP.

HTTPS requests provide higher security but are billed differently than HTTP requests. For more information, see Product Billing.

The following code shows how to configure the SDK to use HTTPS:

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { httpdns } from '@aliyun/httpdns';

const ACCOUNT_ID = 'Replace this with the Account ID from the Alibaba Cloud HTTPDNS console'

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    httpdns.configService(ACCOUNT_ID, {
      context: this.context,
      // ************* Start: Configure whether to use HTTPS requests *************
      useHttps: true,
      // ************* End: Configure whether to use HTTPS requests *************
    });
  }
  // Other code is omitted.
}

Allow the use of expired IP addresses

The SDK follows the DNS protocol and caches resolution results based on their time-to-live (TTL). This improves the efficiency of getting IP addresses for application network requests. If the cache expires and the application calls the resolution operation to get an IP address, the following situations may occur:

1. If the application calls a synchronous non-blocking API operation, an empty result is returned. This happens because the cache is expired and the SDK cannot immediately retrieve a new result from the server. To avoid blocking the thread, fall back to resolution using Local DNS.

2. When an app calls an asynchronous API, the SDK requests a new resolution result from the server. Because this process takes time, a synchronous API call blocks the thread until the new result is returned.

The SDK provides a setting to reuse expired IP addresses. If this option is set to YES, the API immediately returns a cached IP address even if it has expired. This reduces DNS resolution time and improves network request performance. After returning the expired IP address, the SDK starts an asynchronous thread to resolve the domain name and get a new resolution result.

This option has minimal side effects. This is especially true if the resolution configuration does not change often, such as for a primary site or static gateway domain names. If a domain name's resolution changes, this option affects only the first request after the cache expires. The SDK immediately starts a resolution update when it is called and finds an expired IP address.

The following code shows how to disallow the use of expired IP addresses:

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { httpdns } from '@aliyun/httpdns';

const ACCOUNT_ID = 'Replace this with the Account ID from the Alibaba Cloud HTTPDNS console'

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // Configure HTTPDNS
    httpdns.configService(ACCOUNT_ID, {
      context: this.context,
      // ************* Start: Configure whether to allow the use of expired IP addresses *************
      enableExpiredIp: false,
      // ************* End: Configure whether to allow the use of expired IP addresses *************
    })
  }
  // Other code is omitted.
}

Enable local caching

The enableDiskCache parameter controls whether resolution results are stored in the local cache. By default, this feature is disabled (false).

If this feature is enabled, the results of each resolution are cached locally. The next time the application starts, it loads the cached resolution results from local storage. This speeds up the process of obtaining resolution results at application startup.

After you enable local caching, you can use expiredThresholdMillis to configure the cache expiration time. When the application starts, it loads the cache from the persistent layer into memory. This parameter causes the application to discard any resolution results that have been expired for longer than the expiredThresholdMillis duration. The default value is 0 ms.

The following code shows how to enable local caching:

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { httpdns } from '@aliyun/httpdns';

const ACCOUNT_ID = 'Replace this with the Account ID from the Alibaba Cloud HTTPDNS console'

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // Configure HTTPDNS
    httpdns.configService(ACCOUNT_ID, {
      context: this.context,
      // ************* Start: Configure whether to enable local caching *************
      enableDiskCache: true,
      expiredThresholdMillis: 3600000,
      // ************* End: Configure whether to enable local caching *************
    })
  }
  // Other code is omitted.
}

Enable automatic resolution on network changes

You can configure whether to automatically re-resolve previously resolved domain names when the network changes. By default, this feature is enabled (true).

When the network changes, cached resolution results may become invalid. Re-resolution is required to obtain the correct results.

The following code shows how to disable automatic resolution on network changes:

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { httpdns } from '@aliyun/httpdns';

const ACCOUNT_ID = 'Replace this with the Account ID from the Alibaba Cloud HTTPDNS console'

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // Configure HTTPDNS
    httpdns.configService(ACCOUNT_ID, {
      context: this.context,
      // ************* Start: Configure whether to enable automatic resolution on network changes *************
      reResolveCachedHostsAfterNetworkChanged: false,
      // ************* End: Configure whether to enable automatic resolution on network changes *************
    })
  }
  // Other code is omitted.
}

Timeout configuration

You can configure the timeout for domain name resolution requests. The default timeout is 2000 ms.

The following code shows the configuration:

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { httpdns } from '@aliyun/httpdns';

const ACCOUNT_ID = 'Replace this with the Account ID from the Alibaba Cloud HTTPDNS console'

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // Configure HTTPDNS
    httpdns.configService(ACCOUNT_ID, {
      context: this.context,
      // ************* Start: Configure timeout duration *************
      timeoutInMs: 3000
      // ************* End: Configure timeout duration *************
    })
  }
  // Other code is omitted.
}

Resolution parameter encryption

You can configure the encryption key for the parameters of the domain name resolution interface. After you enable encryption, the SDK encrypts the domain name, client IP address, custom business parameters, and resolution type before it sends a request to the service. The data is transmitted to the server as ciphertext, which improves security. By default, encryption is disabled.

The following code shows the configuration:

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { httpdns } from '@aliyun/httpdns';

const ACCOUNT_ID = 'Replace this with the Account ID from the Alibaba Cloud HTTPDNS console'
const AES_SECRET_KEY = 'Replace this with the AES encryption key from the Alibaba Cloud HTTPDNS console'

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // Configure HTTPDNS
    httpdns.configService(ACCOUNT_ID, {
      context: this.context,
      // ************* Start: Configure interface encryption key *************
      aesSecretKey: AES_SECRET_KEY,
      // ************* End: Configure interface encryption key *************
    })
  }
  // Other code is omitted.
}