feat: sync httpdns sdk/platform updates without large binaries
This commit is contained in:
robin
133
HttpDNSSDK/docs/Flutter SDK集成文档.md
Normal file
133
HttpDNSSDK/docs/Flutter SDK集成文档.md
Normal file
@@ -0,0 +1,133 @@
|
||||
# Flutter SDK 集成文档（Edge HTTPDNS）
|
||||
|
||||
## 1. 版本与依赖
|
||||
|
||||
- SDK 插件：`HttpDNSSDK/sdk/flutter/new_httpdns`
|
||||
- 环境要求：Flutter 2.15+ / Dart 2.15+
|
||||
|
||||
在 `pubspec.yaml` 中引用本地插件：
|
||||
|
||||
```yaml
|
||||
dependencies:
|
||||
new_httpdns:
|
||||
path: path/to/sdk/flutter/new_httpdns
|
||||
```
|
||||
|
||||
执行 `flutter pub get` 完成安装。
|
||||
|
||||
## 2. SNI 行为说明（关键）
|
||||
|
||||
1. **/resolve 请求链路**（SDK -> 你的 HTTPDNS 服务域名）
|
||||
- 走标准 HTTPS，默认携带 SNI（用于路由到边缘控制节点）。
|
||||
|
||||
2. **业务请求链路**（拿到 CDN IP 后发起业务 HTTPS）
|
||||
- **IP 直连 + No-SNI**：使用 `TrustAPPHttpdnsHttpAdapter` 进行请求。
|
||||
- 逻辑：解析域名 -> 拿到 IP 列表 -> `uri.replace(host: ip)` -> `req.headers.host = uri.host` -> **清空 SNI**。
|
||||
- 仅支持 HTTPS URL。
|
||||
|
||||
## 3. 初始化 SDK（推荐用 TrustAPP 封装）
|
||||
|
||||
### Dart
|
||||
|
||||
```dart
|
||||
import 'package:new_httpdns/new_httpdns.dart';
|
||||
|
||||
bool ok = await TrustAPPHttpdns.init(
|
||||
appId: "your-app-id",
|
||||
primaryServiceHost: "httpdns.example.com",
|
||||
backupServiceHost: "httpdns-backup.example.com",
|
||||
servicePort: 443,
|
||||
secretKey: "your-sign-secret" // 可选，开启签名校验需传入
|
||||
);
|
||||
|
||||
if (ok) {
|
||||
print("Edge HTTPDNS 初始化成功");
|
||||
}
|
||||
```
|
||||
|
||||
## 4. 解析域名获取 CDN IP
|
||||
|
||||
### Dart
|
||||
|
||||
```dart
|
||||
// V1 风格解析接口
|
||||
Map<String, dynamic> result = await TrustAPPHttpdns.resolveHost(
|
||||
"api.example.com",
|
||||
qtype: 'A', // 可选 'A' 或 'AAAA'
|
||||
cip: '1.2.3.4' // 可选，模拟客户端 IP
|
||||
);
|
||||
|
||||
List<String> ipv4s = result['ipv4'];
|
||||
int ttl = result['ttl'];
|
||||
```
|
||||
|
||||
## 5. 业务请求接入方式
|
||||
|
||||
使用 `TrustAPPHttpdnsHttpAdapter` 实现“SNI 隐匿”业务请求。
|
||||
|
||||
### Dart
|
||||
|
||||
```dart
|
||||
final adapter = TrustAPPHttpdns.createHttpAdapter(
|
||||
options: const TrustAPPHttpdnsAdapterOptions(
|
||||
connectTimeoutMs: 3000,
|
||||
readTimeoutMs: 5000,
|
||||
ipType: 'auto', // auto/ipv4/ipv6
|
||||
)
|
||||
);
|
||||
|
||||
try {
|
||||
final res = await adapter.request(
|
||||
Uri.parse("https://api.example.com/path?x=1"),
|
||||
method: 'GET',
|
||||
headers: {'Custom-Header': 'Value'},
|
||||
body: null
|
||||
);
|
||||
|
||||
print("Status Code: ${res.statusCode}");
|
||||
print("Body Length: ${res.body.length}");
|
||||
print("Used IP: ${res.usedIp}");
|
||||
} catch (e) {
|
||||
print("请求失败: $e");
|
||||
}
|
||||
```
|
||||
|
||||
## 6. 其他常用接口
|
||||
|
||||
```dart
|
||||
// 1. 设置预解析域名
|
||||
await TrustAPPHttpdns.setPreResolveHosts(["api.example.com", "img.example.com"]);
|
||||
|
||||
// 2. 只有开启缓存时可用
|
||||
Map<String, List<String>> cacheRes = await TrustAPPHttpdns.resolveHostSyncNonBlocking("api.example.com");
|
||||
|
||||
// 3. 开启持久化缓存（重启 App 后任然可用）
|
||||
await TrustAPPHttpdns.setPersistentCacheIPEnabled(true);
|
||||
|
||||
// 4. 控制台日志（建议仅调试开启）
|
||||
await TrustAPPHttpdns.setLogEnabled(true);
|
||||
```
|
||||
|
||||
## 7. 验证建议
|
||||
|
||||
1. **验证 /resolve**
|
||||
- 观察控制台日志或抓包工具，解析请求应指向 `https://<serviceHost>:<servicePort>/resolve...`。
|
||||
|
||||
2. **验证业务请求**
|
||||
- 如果使用 `TrustAPPHttpdnsHttpAdapter`，观察抓包：
|
||||
- TCP 连接 IP 为 CDN 私有/边缘 IP。
|
||||
- HTTP `Host` 为原始域名。
|
||||
- TLS ClientHello 中 **无 SNI** 扩展。
|
||||
|
||||
## 8. 平台配置事项
|
||||
|
||||
- **Android**: 参照 Android SDK 文档配置混淆。
|
||||
- **iOS**: 如果是手动集成 Flutter 插件，请确保 iOS 模块已包含依赖的静态库，并设置 `Allow Arbitrary Loads` (如果启用 HTTP)。
|
||||
|
||||
## 9. 常见问题
|
||||
|
||||
1. **Flutter 端报错：NO_IP_AVAILABLE**
|
||||
- SDK 尚未解析出有效结果，请确认域名是否已在控制台添加并配置规则。
|
||||
|
||||
2. **请求报错：TLS_EMPTY_SNI_FAILED**
|
||||
- 仅支持 HTTPS 网站。如果所有 IP 尝试均失败，请检查网络权限及服务端防火墙。
|
||||
161
HttpDNSSDK/docs/HTTPDNS SDK 集成文档（Android）.md
Normal file
161
HttpDNSSDK/docs/HTTPDNS SDK 集成文档（Android）.md
Normal file
@@ -0,0 +1,161 @@
|
||||
# HTTPDNS SDK 集成文档（Android）
|
||||
|
||||
## 1. 版本与依赖
|
||||
|
||||
- SDK 模块：`HttpDNSSDK/sdk/android/httpdns-sdk`
|
||||
- `minSdkVersion`：19
|
||||
- `targetSdkVersion`：33
|
||||
- `compileSdk`：33
|
||||
|
||||
将发布包中的 `jar/aar` 放到应用模块 `libs/`，在 `app/build.gradle` 中添加：
|
||||
|
||||
```gradle
|
||||
dependencies {
|
||||
implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])
|
||||
implementation 'androidx.appcompat:appcompat:1.6.1'
|
||||
}
|
||||
```
|
||||
|
||||
## 2. SNI 行为说明（关键）
|
||||
|
||||
当前 SDK 行为与代码一致：
|
||||
|
||||
1. `/resolve` 请求链路（SDK -> 你的 HTTPDNS 服务域名）
|
||||
- 走域名 HTTPS
|
||||
- 默认 TLS 行为（会带 SNI）
|
||||
|
||||
2. 业务请求链路（拿到 CDN IP 后发起业务 HTTPS）
|
||||
- 使用 `HttpDnsHttpAdapter`：按 IP 建连，`Host` 保留原域名，并清空 SNI（No-SNI）
|
||||
|
||||
## 3. 初始化 SDK（推荐用 V1 客户端）
|
||||
|
||||
### Kotlin
|
||||
|
||||
```kotlin
|
||||
import com.newsdk.sdk.android.httpdns.HttpDnsV1Client
|
||||
import com.newsdk.sdk.android.httpdns.HttpDnsService
|
||||
|
||||
val service: HttpDnsService = HttpDnsV1Client.init(
|
||||
applicationContext,
|
||||
"your-app-id",
|
||||
"https://httpdns.example.com:8445", // serviceUrl，支持填写协议+端口
|
||||
"your-sign-secret" // 可传 ""
|
||||
)
|
||||
```
|
||||
|
||||
### Java
|
||||
|
||||
```java
|
||||
import com.newsdk.sdk.android.httpdns.HttpDnsService;
|
||||
import com.newsdk.sdk.android.httpdns.HttpDnsV1Client;
|
||||
|
||||
HttpDnsService service = HttpDnsV1Client.init(
|
||||
getApplicationContext(),
|
||||
"your-app-id",
|
||||
"https://httpdns.example.com:8445", // serviceUrl
|
||||
"your-sign-secret" // 可传 ""
|
||||
);
|
||||
```
|
||||
|
||||
## 4. 解析域名获取 CDN IP
|
||||
|
||||
### Kotlin
|
||||
|
||||
```kotlin
|
||||
import com.newsdk.sdk.android.httpdns.HTTPDNSResult
|
||||
|
||||
val result: HTTPDNSResult = HttpDnsV1Client.resolveHost(
|
||||
service = service,
|
||||
host = "api.example.com",
|
||||
qtype = "A", // "A" 或 "AAAA"
|
||||
cip = null // 可选，客户端 IP 透传
|
||||
)
|
||||
|
||||
val ips = result.ips ?: emptyArray()
|
||||
```
|
||||
|
||||
### Java
|
||||
|
||||
```java
|
||||
import com.newsdk.sdk.android.httpdns.HTTPDNSResult;
|
||||
|
||||
HTTPDNSResult result = HttpDnsV1Client.resolveHost(
|
||||
service,
|
||||
"api.example.com",
|
||||
"A",
|
||||
null
|
||||
);
|
||||
|
||||
String[] ips = result.getIps();
|
||||
```
|
||||
|
||||
## 5. 业务请求接入方式
|
||||
|
||||
### 使用 `HttpDnsHttpAdapter`（IP 直连 + No-SNI）
|
||||
|
||||
业务请求侧做“隐匿 SNI”。该适配器仅支持 HTTPS URL。
|
||||
|
||||
```kotlin
|
||||
import com.newsdk.sdk.android.httpdns.HttpDnsV1Client
|
||||
import com.newsdk.sdk.android.httpdns.network.HttpDnsAdapterOptions
|
||||
import com.newsdk.sdk.android.httpdns.network.HttpDnsAdapterRequest
|
||||
|
||||
val adapter = HttpDnsV1Client.buildHttpClientAdapter(
|
||||
service,
|
||||
HttpDnsAdapterOptions.Builder()
|
||||
.setConnectTimeoutMillis(3000)
|
||||
.setReadTimeoutMillis(5000)
|
||||
.setRequestIpType(com.newsdk.sdk.android.httpdns.RequestIpType.auto)
|
||||
.build()
|
||||
)
|
||||
|
||||
val req = HttpDnsAdapterRequest(
|
||||
"GET",
|
||||
"https://api.example.com/path?x=1"
|
||||
)
|
||||
|
||||
val resp = adapter.execute(req)
|
||||
val code = resp.statusCode
|
||||
val bodyBytes = resp.body
|
||||
val usedIp = resp.usedIp
|
||||
```
|
||||
|
||||
## 6. 预解析与常用接口
|
||||
|
||||
```kotlin
|
||||
service.setPreResolveHosts(listOf("api.example.com", "img.example.com"))
|
||||
|
||||
val r1 = service.getHttpDnsResultForHostSync("api.example.com", com.newsdk.sdk.android.httpdns.RequestIpType.auto)
|
||||
val r2 = service.getHttpDnsResultForHostSyncNonBlocking("api.example.com", com.newsdk.sdk.android.httpdns.RequestIpType.auto)
|
||||
```
|
||||
|
||||
- `Sync`：允许阻塞等待刷新结果（上限受 timeout 等配置影响）
|
||||
- `NonBlocking`：快速返回当前可用缓存/结果，不阻塞等待
|
||||
|
||||
## 7. 验证建议
|
||||
|
||||
1. 验证 `/resolve`
|
||||
- 抓包看目标应为 `https://<serviceUrl>/resolve...`（即初始化时传入的 URL）
|
||||
|
||||
2. 验证业务请求（若使用 `HttpDnsHttpAdapter`）
|
||||
- 目标地址应是 CDN IP
|
||||
- HTTP `Host` 应为原域名
|
||||
- TLS ClientHello 不应携带 SNI（No-SNI）
|
||||
|
||||
## 8. 混淆配置
|
||||
|
||||
```proguard
|
||||
-keep class com.newsdk.sdk.android.** { *; }
|
||||
```
|
||||
|
||||
## 9. 常见问题
|
||||
|
||||
1. HTTPDNS 没生效
|
||||
- 检查是否真正使用了 SDK 返回 IP（或用了 `HttpDnsHttpAdapter`）
|
||||
- 检查失败回退逻辑是否总是直接走了系统 DNS
|
||||
|
||||
2. 使用 `HttpDnsHttpAdapter` 仍失败
|
||||
- 只支持 HTTPS URL
|
||||
|
||||
3. 线上不要开启不安全证书
|
||||
- `HttpDnsAdapterOptions.Builder#setAllowInsecureCertificatesForDebugOnly(true)` 仅限调试环境
|
||||
124
HttpDNSSDK/docs/iOS SDK集成文档.md
Normal file
124
HttpDNSSDK/docs/iOS SDK集成文档.md
Normal file
@@ -0,0 +1,124 @@
|
||||
# iOS SDK 集成文档（Edge HTTPDNS）
|
||||
|
||||
## 1. 版本与依赖
|
||||
|
||||
- SDK 模块：`HttpDNSSDK/sdk/ios/NewHttpDNS`
|
||||
- 支持系统：iOS 11.0+
|
||||
- 集成方式：
|
||||
- **CocoaPods**：在 `Podfile` 中添加 `pod 'NewHTTPDNS', :path => 'path/to/sdk/ios'`
|
||||
- **手动集成**：将 `NewHttpDNS` 源码或编译后的静态库导入项目，并添加依赖的系统库（Foundation, CFNetwork, SystemConfiguration）。
|
||||
|
||||
## 2. SNI 行为说明（关键）
|
||||
|
||||
1. **/resolve 请求链路**（SDK -> 你的 HTTPDNS 服务域名）
|
||||
- 使用标准 HTTPS 请求。
|
||||
- 默认携带 SNI（用于通过 WAF/CDN 识别服务域名）。
|
||||
|
||||
2. **业务请求链路**（拿到 CDN IP 后通过 `HttpdnsEdgeService` 发起业务 HTTPS）
|
||||
- **IP 直连 + No-SNI**：SDK 会建立与 IP 的连接，并将 `NSURLRequest` 的 `URL` 替换为 IP，同时保留 `Host` 头部为原域名。
|
||||
- **证书校验**：由于清空了 SNI，常规 SNI 校验会跳过，需确保后端节点支持 Host 匹配证书。
|
||||
|
||||
## 3. 初始化 SDK（推荐用 EdgeService 封装）
|
||||
|
||||
### Objective-C
|
||||
|
||||
```objective-c
|
||||
#import <NewHttpDNS/HttpdnsEdgeService.h>
|
||||
|
||||
HttpdnsEdgeService *service = [[HttpdnsEdgeService alloc] initWithAppId:@"your-app-id"
|
||||
primaryServiceHost:@"httpdns.example.com"
|
||||
backupServiceHost:@"httpdns-backup.example.com"
|
||||
servicePort:443
|
||||
signSecret:@"your-sign-secret"];
|
||||
```
|
||||
|
||||
### Swift
|
||||
|
||||
```swift
|
||||
import NewHttpDNS
|
||||
|
||||
let service = HttpdnsEdgeService(appId: "your-app-id",
|
||||
primaryServiceHost: "httpdns.example.com",
|
||||
backupServiceHost: "httpdns-backup.example.com",
|
||||
servicePort: 443,
|
||||
signSecret: "your-sign-secret")
|
||||
```
|
||||
|
||||
## 4. 解析域名获取 CDN IP
|
||||
|
||||
### Objective-C
|
||||
|
||||
```objective-c
|
||||
[service resolveHost:@"api.example.com"
|
||||
queryType:@"A"
|
||||
completion:^(HttpdnsEdgeResolveResult * _Nullable result, NSError * _Nullable error) {
|
||||
if (result) {
|
||||
NSLog(@"IPv4s: %@", result.ipv4s);
|
||||
NSLog(@"TTL: %ld", (long)result.ttl);
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
### Swift
|
||||
|
||||
```swift
|
||||
service.resolveHost("api.example.com", queryType: "A") { result, error in
|
||||
if let ips = result?.ipv4s {
|
||||
print("Resolved IPs: \(ips)")
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 5. 业务请求接入方式
|
||||
|
||||
使用 `HttpdnsEdgeService` 提供的 `requestURL` 方法，自动处理 IP 直连与 SNI 隐藏。
|
||||
|
||||
### Objective-C
|
||||
|
||||
```objective-c
|
||||
NSURL *url = [NSURL URLWithString:@"https://api.example.com/path?x=1"];
|
||||
[service requestURL:url
|
||||
method:@"GET"
|
||||
headers:@{@"Custom-Header": @"Value"}
|
||||
body:nil
|
||||
completion:^(NSData * _Nullable data, NSHTTPURLResponse * _Nullable response, NSError * _Nullable error) {
|
||||
if (!error) {
|
||||
NSLog(@"Status Code: %ld", (long)response.statusCode);
|
||||
// 处理 data
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
### Swift
|
||||
|
||||
```swift
|
||||
let url = URL(string: "https://api.example.com/path?x=1")!
|
||||
service.requestURL(url, method: "GET", headers: ["Custom-Header": "Value"], body: nil) { data, response, error in
|
||||
if let resp = response {
|
||||
print("Status Code: \(resp.statusCode)")
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 6. 验证建议
|
||||
|
||||
1. **验证 /resolve**
|
||||
- 观察网络请求，应指向 `https://httpdns.example.com/resolve?appId=...&dn=...`。
|
||||
- 确认返回 JSON 包含 `code: "SUCCESS"`。
|
||||
|
||||
2. **验证业务请求**
|
||||
- 确认请求握手阶段不携带 SNI 扩展。
|
||||
- 确认请求的 TCP 连接目标为解析出的私有 IP/CDN IP。
|
||||
|
||||
## 7. 常见问题
|
||||
|
||||
1. **编译报错：找不到头文件**
|
||||
- 请确认 `Header Search Paths` 包含 SDK 路径。
|
||||
- 如果使用 CocoaPods，请确保执行 `pod install` 并打开 `.xcworkspace`。
|
||||
|
||||
2. **请求返回 403 (Sign Invalid)**
|
||||
- 确认控制台已开启“签名校验”，且本地传入的 `signSecret` 与控制台一致。
|
||||
- 确认系统时间正常（差值超过 30s 可能导致签名失效）。
|
||||
|
||||
3. **HTTPS 证书验证失败**
|
||||
- 检查 `HttpdnsEdgeService` 是否能正确匹配证书，通常是在 No-SNI 模式下通过 `Host` 字段匹配。
|
||||
Reference in New Issue
Block a user