HTTPDNS:Integrate the Flutter SDK

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:

AliyunHttpdns.setLogEnabled(true);

// Custom log handler (optional)
AliyunHttpdns.setLogHandler((message) {
  print(message);
});

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 = AliyunHttpdns.getSessionId();
print("SessionId = $sessionId");

3.2. Domain name resolution

await AliyunHttpdns.setPreResolveHosts(["www.aliyun.com", "www.example.com"], ipType: HttpdnsIpType.auto);

Future<void> _resolve() async {
  final result = await AliyunHttpdns.resolveHostSyncNonBlocking('www.aliyun.com', ipType: HttpdnsIpType.auto);
  final ipv4List = result?.ips ?? [];
  final ipv6List = result?.ipv6s ?? [];
  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: 30);
  client.maxConnectionsPerHost = 8;
}

// Configure a connection factory based on HTTPDNS
// This solution was designed and implemented by the EMAS team. 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 result = await AliyunHttpdns.resolveHostSyncNonBlocking(domain, ipType: HttpdnsIpType.auto);
    final List<String> ipv4 = result?.ips ?? [];
    final List<String> ipv6 = result?.ipv6s ?? [];
    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 {
      final config = AliyunHttpdnsConfig(
        accountId: Your AccountId,
        secretKey: 'Your SecretKey',
        httpsEnabled: true,
        reuseExpiredIPEnabled: true,
      );
      await AliyunHttpdns.init(config);
      AliyunHttpdns.setLogEnabled(true);
      
      // Set pre-resolve hosts
      await AliyunHttpdns.setPreResolveHosts(['www.aliyun.com'], ipType: HttpdnsIpType.auto);
    } 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();
}

5.3.1 Synchronous non-blocking resolution (recommended)

Immediately returns the cached result. If the cache is not hit, it returns null and initiates a request in the background.

final result = await AliyunHttpdns.resolveHostSyncNonBlocking(
  'www.aliyun.com', 
  ipType: HttpdnsIpType.auto,
);

// With SDNS parameters
final result2 = await AliyunHttpdns.resolveHostSyncNonBlocking(
  'www.aliyun.com',
  ipType: HttpdnsIpType.auto,
  sdnsParams: {'key': 'value'},
  cacheKey: 'custom_cache_key',
);

5.3.2 Synchronous blocking resolution

Blocks until a result is obtained or the request times out.

final result = await AliyunHttpdns.resolveHostSync(
  'www.aliyun.com',
  ipType: HttpdnsIpType.auto,
);

// With SDNS parameters
final result2 = await AliyunHttpdns.resolveHostSync(
  'www.aliyun.com',
  ipType: HttpdnsIpType.auto,
  sdnsParams: {'key': 'value'},
  cacheKey: 'custom_cache_key',
);

5.3.3 Asynchronous callback resolution

Returns the resolution result through a callback function.

await AliyunHttpdns.resolveHostAsync(
  'www.aliyun.com',
  ipType: HttpdnsIpType.auto,
  callback: (result) {
    print('Resolution result: $result');
  },
);

// With SDNS parameters
await AliyunHttpdns.resolveHostAsync(
  'www.aliyun.com',
  ipType: HttpdnsIpType.auto,
  sdnsParams: {'key': 'value'},
  cacheKey: 'custom_cache_key',
  callback: (result) {
    print('Resolution result: $result');
  },
);

Parameter description

Returned data structure (ResolveResult)

Detailed upgrade steps

dependencies:aliyun_httpdns: ^2.0.0

flutter pub upgrade aliyun_httpdns

// 1.x: Two-stage initialization
await AliyunHttpdns.init(
  accountId: Your AccountId,
  secretKey: "your_secret_key",
  aesSecretKey: "your_aes_key",
);

await AliyunHttpdns.setHttpsRequestEnabled(true);
await AliyunHttpdns.setPersistentCacheIPEnabled(true);
await AliyunHttpdns.setReuseExpiredIPEnabled(true);
await AliyunHttpdns.setPreResolveAfterNetworkChanged(true);
await AliyunHttpdns.setIPRankingList({'www.aliyun.com': 443});

await AliyunHttpdns.build();

final config = AliyunHttpdnsConfig(
  accountId: Your AccountId,
  secretKey: 'your_secret_key',
  aesSecretKey: 'your_aes_key',
  httpsEnabled: true,
  persistentCacheEnabled: true,
  reuseExpiredIPEnabled: true,
  preResolveAfterNetworkChanged: true,
  ipRankingDatasource: {'www.aliyun.com': 443},
);
await AliyunHttpdns.init(config);

final res = await AliyunHttpdns.resolveHostSyncNonBlocking(
  'www.aliyun.com',
  ipType: 'both',
);
final ipv4s = res['ipv4'] ?? [];
final ipv6s = res['ipv6'] ?? [];

final result = await AliyunHttpdns.resolveHostSyncNonBlocking(
  'www.aliyun.com',
  ipType: HttpdnsIpType.auto,
);
final ipv4s = result?.ips ?? [];
final ipv6s = result?.ipv6s ?? [];

await AliyunHttpdns.setPreResolveHosts(['www.aliyun.com']);

await AliyunHttpdns.setPreResolveHosts(['www.aliyun.com']);

AliyunHttpdns.setLogHandler((message) {
  print(message);
});

await AliyunHttpdns.cleanAllHostCache();

// Clear all caches
await AliyunHttpdns.cleanHostCache(null);

// Clear the cache for a specified domain name (new)
await AliyunHttpdns.cleanHostCache(['www.aliyun.com']);

API upgrade mapping table (1.x → 2.0)

Detailed upgrade steps

dependencies:aliyun_httpdns: ^1.0.0

flutter pub upgrade aliyun_httpdns

// 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"]
);

// 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();

// 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 : '';

// 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 : '';

// 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"
);

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

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

await _aliyunHttpDns.enableLog(true);

await AliyunHttpdns.setLogEnabled(true);

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

String? sessionId = await AliyunHttpdns.getSessionId();

await AliyunHttpdns.cleanAllHostCache();

await AliyunHttpdns.setPersistentCacheIPEnabled(true);

API upgrade mapping table