HTTPDNS:Integrate the Flutter plugin

2.2.1. Verify the native SDK version

The plugin integrates the native HTTPDNS SDK for each platform. The current versions are:

• Android: com.aliyun.ams:alicloud-android-httpdns:2.6.7

• iOS: AlicloudHTTPDNS:3.4.0

To update the SDK version, see the update instructions below.

2.2.2. Update the Android SDK version

Edit the packages/aliyun_httpdns/android/build.gradle file and modify the dependency version:

dependencies {
    implementation 'androidx.annotation:annotation:1.8.0'
    // Update to your required version
    implementation 'com.aliyun.ams:alicloud-android-httpdns:2.6.7'
}

For available versions, see Android SDK release notes.

2.2.3. Update the iOS SDK version

Edit the packages/aliyun_httpdns/ios/aliyun_httpdns.podspec file and modify the dependency version:

Pod::Spec.new do |s|
  # ... other configurations ...
  
  s.dependency 'Flutter'
  # Update to your required version
  s.dependency 'AlicloudHTTPDNS', '3.4.0'
  
  # ... other configurations ...
end

For available versions, see iOS SDK release notes.

2.2.4. Rebuild the project

After updating the version, rebuild the project:

Android:

flutter clean
flutter pub get
flutter build apk  # or other build commands

iOS:

flutter clean
flutter pub get
cd ios
pod install
cd ..
flutter build ios

3.1.1. Log configuration

To output HTTPDNS logs during application development, you can call the log output control method to enable logging. The following code provides an example:

await AliyunHttpdns.setLogEnabled(true);
print("enableLog success");

3.1.2. SessionId recording

While the application is running, you can call the method to retrieve the sessionId and record it in your application's data collection system. The sessionId identifies a single application run. It can be used to query resolution logs for a specific run during online troubleshooting. The following code provides an example:

final sessionId = await AliyunHttpdns.getSessionId();
print("SessionId = $sessionId");

3.2. Domain name resolution

await AliyunHttpdns.setPreResolveHosts(["www.aliyun.com", "www.example.com"], ipType: 'both');
print("preResolveHosts success");

Future<void> _resolve() async {
  final res = await AliyunHttpdns.resolveHostSyncNonBlocking('www.aliyun.com', ipType: 'both');
  final ipv4List = res['ipv4'] ?? [];
  final ipv6List = res['ipv6'] ?? [];
  print('IPv4: $ipv4List');
  print('IPv6: $ipv6List');
}

4.2.1. Custom HTTP client adapter implementation

For the custom adapter implementation, see the lib/net/httpdns_http_client_adapter.dart file. This solution was designed and implemented by the EMAS team. If you reference this solution, please provide attribution. The adapter intercepts HTTP requests, calls HTTPDNS for domain name resolution, and uses the resolved IP address to create a socket connection.

This example supports three networking libraries: Dio, HttpClient, and the http package. The code is as follows:

import 'dart:io';
import 'package:dio/io.dart';
import 'package:http/http.dart' as http;
import 'package:http/io_client.dart';
import 'package:flutter/foundation.dart';
import 'package:aliyun_httpdns/aliyun_httpdns.dart';

// Dio adapter
IOHttpClientAdapter buildHttpdnsHttpClientAdapter() {
  final HttpClient client = HttpClient();
  _configureHttpClient(client);
  _configureConnectionFactory(client);

  final IOHttpClientAdapter adapter = IOHttpClientAdapter(createHttpClient: () => client)
    ..validateCertificate = (cert, host, port) => true;
  return adapter;
}

// Native HttpClient
HttpClient buildHttpdnsNativeHttpClient() {
  final HttpClient client = HttpClient();
  _configureHttpClient(client);
  _configureConnectionFactory(client);
  return client;
}

// http package adapter
http.Client buildHttpdnsHttpPackageClient() {
  final HttpClient httpClient = buildHttpdnsNativeHttpClient();
  return IOClient(httpClient);
}

// HttpClient basic configuration
void _configureHttpClient(HttpClient client) {
  client.findProxy = (Uri _) => 'DIRECT';
  client.idleTimeout = const Duration(seconds: 90);
  client.maxConnectionsPerHost = 8;
}

// Configure a connection factory based on HTTPDNS
// This solution was designed and implemented by the EMAS team. Please provide attribution if you reference it.
void _configureConnectionFactory(HttpClient client) {
  client.connectionFactory = (Uri uri, String? proxyHost, int? proxyPort) async {
    final String domain = uri.host;
    final bool https = uri.scheme.toLowerCase() == 'https';
    final int port = uri.port == 0 ? (https ? 443 : 80) : uri.port;

    final List<InternetAddress> targets = await _resolveTargets(domain);
    final Object target = targets.isNotEmpty ? targets.first : domain;

    if (!https) {
      return Socket.startConnect(target, port);
    }

    // HTTPS: First TCP, then TLS (SNI=domain name), and keep it cancellable
    bool cancelled = false;
    final Future<ConnectionTask<Socket>> rawStart = Socket.startConnect(target, port);
    final Future<Socket> upgraded = rawStart.then((task) async {
      final Socket raw = await task.socket;
      if (cancelled) {
        raw.destroy();
        throw const SocketException('Connection cancelled');
      }
      final SecureSocket secure = await SecureSocket.secure(
        raw,
        host: domain, // Important: Use the original domain name as the SNI
      );
      if (cancelled) {
        secure.destroy();
        throw const SocketException('Connection cancelled');
      }
      return secure;
    });
    return ConnectionTask.fromSocket(
      upgraded,
      () {
        cancelled = true;
        try {
          rawStart.then((t) => t.cancel());
        } catch (_) {}
      },
    );
  };
}

// Resolve the target IP list through HTTPDNS
Future<List<InternetAddress>> _resolveTargets(String domain) async {
  try {
    final res = await AliyunHttpdns.resolveHostSyncNonBlocking(domain, ipType: 'both');
    final List<String> ipv4 = res['ipv4'] ?? [];
    final List<String> ipv6 = res['ipv6'] ?? [];
    final List<InternetAddress> targets = [
      ...ipv4.map(InternetAddress.tryParse).whereType<InternetAddress>(),
      ...ipv6.map(InternetAddress.tryParse).whereType<InternetAddress>(),
    ];
    if (targets.isEmpty) {
      debugPrint('[dio] HTTPDNS no result for $domain, fallback to system DNS');
    } else {
      debugPrint('[dio] HTTPDNS resolved $domain -> ${targets.first.address}');
    }
    return targets;
  } catch (e) {
    debugPrint('[dio] HTTPDNS resolve failed: $e, fallback to system DNS');
    return const <InternetAddress>[];
  }
}

4.2.2. Adapter integration and usage

For adapter integration, see the lib/main.dart file. First, initialize HTTPDNS. Then, configure the networking library to use the custom adapter. The following code provides an example:

class _MyHomePageState extends State<MyHomePage> {
  late final Dio _dio;
  late final HttpClient _httpClient;
  late final http.Client _httpPackageClient;

  @override
  void initState() {
    super.initState();
    
    // Initialize HTTPDNS
    _initHttpDnsOnce();
    
    // Configure the networking library to use the HTTPDNS adapter
    _dio = Dio();
    _dio.httpClientAdapter = buildHttpdnsHttpClientAdapter();
    _dio.options.headers['Connection'] = 'keep-alive';
    
    _httpClient = buildHttpdnsNativeHttpClient();
    _httpPackageClient = buildHttpdnsHttpPackageClient();
  }

  Future<void> _initHttpDnsOnce() async {
    try {
      await AliyunHttpdns.init(
        accountId: 139450,
        secretKey: 'Your SecretKey',
      );
      await AliyunHttpdns.setHttpsRequestEnabled(true);
      await AliyunHttpdns.setLogEnabled(true);
      await AliyunHttpdns.setPersistentCacheIPEnabled(true);
      await AliyunHttpdns.setReuseExpiredIPEnabled(true);
      await AliyunHttpdns.build();
      
      // Set pre-resolve hosts
      await AliyunHttpdns.setPreResolveHosts(['www.aliyun.com'], ipType: 'both');
    } catch (e) {
      debugPrint('[httpdns] init failed: $e');
    }
  }
}

When you use the configured networking library to make a request, it automatically uses HTTPDNS for domain name resolution:

// Use Dio
final response = await _dio.get('https://www.aliyun.com');

// Use HttpClient
final request = await _httpClient.getUrl(Uri.parse('https://www.aliyun.com'));
final response = await request.close();

// Use the http package
final response = await _httpPackageClient.get(Uri.parse('https://www.aliyun.com'));

4.2.3. Clean up resources

When the component is destroyed, you must clean up the related resources:

@override
void dispose() {
  _urlController.dispose();
  _httpClient.close();
  _httpPackageClient.close();
  super.dispose();
}

1. Update the dependency version

pubspec.yaml

dependencies:aliyun_httpdns: ^1.0.0

Run the update:

flutter pub upgrade aliyun_httpdns

2. Refactor the initialization code

Before upgrade

// Old version: Singleton pattern + one-step initialization
final _aliyunHttpDns = AliyunHttpDns();

await _aliyunHttpDns.init(
  "YOUR_ACCOUNT_ID",              // String type
  secretKey: "your_secret_key",
  aesSecretKey: "your_aes_key",
  region: "",
  timeout: 2000,
  enableHttps: true,
  enableExpireIp: true,
  enableCacheIp: true,
  enableDegradationLocalDns: true,
  preResolveAfterNetworkChanged: true,
  ipRankingMap: {"www.aliyun.com": 80},
  sdnsGlobalParam: {"aa": "bb"},
  bizTags: ["tag1", "tag2"]
);

After upgrade

// New version: Static methods + two-stage initialization

// Stage 1: Initialize basic configurations
await AliyunHttpdns.init(
  accountId: your_account_id,            // int type, required
  secretKey: "your_secret_key",          // Optional
  aesSecretKey: "your_aes_key",          // Optional
);

// Stage 2: Set feature options
await AliyunHttpdns.setHttpsRequestEnabled(true);        // Replaces enableHttps
await AliyunHttpdns.setLogEnabled(true);                 // Replaces enableLog
await AliyunHttpdns.setPersistentCacheIPEnabled(true);   // Replaces enableCacheIp
await AliyunHttpdns.setReuseExpiredIPEnabled(true);      // Replaces enableExpireIp
await AliyunHttpdns.setPreResolveAfterNetworkChanged(true); // Replaces preResolveAfterNetworkChanged

// Stage 3: Build the service (must be called)
await AliyunHttpdns.build();

Notes:

• The region, timeout, enableDegradationLocalDns, ipRankingMap, sdnsGlobalParam, and bizTags parameters have been removed.

• A new build() method has been added. It must be called after configuration is complete.

• All methods are now static. You do not need to create an instance.

3. Update the resolution API

Before upgrade

// Synchronous non-blocking, returns a JSON string
String result = await _aliyunHttpDns.resolve(
  "YOUR_ACCOUNT_ID",          // accountId
  "www.aliyun.com",           // host
  kRequestIpv4AndIpv6,        // requestIpType
);

// Requires manual JSON parsing
Map<String, dynamic> map = json.decode(result);
List<String> ipv4s = List<String>.from(map['ipv4'] ?? []);
List<String> ipv6s = List<String>.from(map['ipv6'] ?? []);

// Use the first IP
String ip = ipv4s.isNotEmpty ? ipv4s.first : '';

After upgrade

// Synchronous non-blocking, returns structured data
Map<String, List<String>> result = await AliyunHttpdns.resolveHostSyncNonBlocking(
  'www.aliyun.com',           // hostname (accountId is not required)
  ipType: 'both',             // Replaces kRequestIpv4AndIpv6
);

// Get the IP list directly
List<String> ipv4s = result['ipv4'] ?? [];
List<String> ipv6s = result['ipv6'] ?? [];

// Use the first IP
String ip = ipv4s.isNotEmpty ? ipv4s.first : '';

Custom resolution parameters:

// Before upgrade
String result = await _aliyunHttpDns.resolve(
  "YOUR_ACCOUNT_ID",
  "www.aliyun.com",
  kRequestIpv4AndIpv6,
  params: {"key": "value"},
  cacheKey: "custom_key"
);

// After upgrade
Map<String, List<String>> result = await AliyunHttpdns.resolveHostSyncNonBlocking(
  'www.aliyun.com',
  ipType: 'both',
  sdnsParams: {"key": "value"},    // Parameter name changed
  cacheKey: "custom_key"
);

4. Update the pre-resolution API

Before upgrade

await _aliyunHttpDns.setPreResolveHosts(
  "YOUR_ACCOUNT_ID",                     // accountId
  ["www.aliyun.com"],
  kRequestIpv4AndIpv6                    // requestIpType
);

After upgrade

await AliyunHttpdns.setPreResolveHosts(
  ["www.aliyun.com"],                     // accountId is not required
  ipType: 'both'                          // Replaces kRequestIpv4AndIpv6
);

5. Update the log configuration

Before upgrade

await _aliyunHttpDns.enableLog(true);

After upgrade

await AliyunHttpdns.setLogEnabled(true);

6. Update SessionId retrieval

Before upgrade

String sessionId = await _aliyunHttpDns.getSessionId("YOUR_ACCOUNT_ID");

After upgrade

String? sessionId = await AliyunHttpdns.getSessionId();

7. Use new features

Clear cache

await AliyunHttpdns.cleanAllHostCache();

Persistent cache configuration

await AliyunHttpdns.setPersistentCacheIPEnabled(true);