{"_id":"@alicloud-emas/httpdns","name":"@alicloud-emas/httpdns","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@alicloud-emas/httpdns","version":"1.0.0","description":"阿里云EMAS HTTPDNS Node.js SDK - 通过HTTP/HTTPS协议提供高性能DNS解析服务","main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=12.0.0","npm":">=6.0.0"},"scripts":{"build":"npm run clean && tsc","build:watch":"tsc --watch","clean":"rimraf dist","test":"jest","test:watch":"jest --watch","test:coverage":"jest --coverage","test:ci":"jest --ci --coverage --watchAll=false","test:integration":"jest --testPathPattern=integration","lint":"eslint 'src/**/*.ts' --ext .ts","lint:fix":"eslint 'src/**/*.ts' --ext .ts --fix","format":"prettier --write 'src/**/*.{ts,js,json}'","format:check":"prettier --check 'src/**/*.{ts,js,json}'","type-check":"tsc --noEmit","validate":"npm run type-check && npm run build","docs":"typedoc src/index.ts","example":"node dist/examples/basic.js","prepare":"npm run build","prepublishOnly":"npm run validate && npm run build","preversion":"npm run validate","postversion":"git push && git push --tags"},"keywords":["httpdns","dns","aliyun","alibaba","sdk","nodejs","typescript"],"author":{"name":"Alibaba Cloud"},"license":"MIT","dependencies":{"axios":"^0.27.2"},"devDependencies":{"@types/jest":"^26.0.24","@types/node":"^12.20.55","@typescript-eslint/eslint-plugin":"^4.33.0","@typescript-eslint/parser":"^4.33.0","ali-oss":"^6.23.0","eslint":"^7.32.0","eslint-config-prettier":"^8.5.0","eslint-plugin-prettier":"^3.4.1","jest":"^26.6.3","prettier":"^2.7.1","rimraf":"^3.0.2","ts-jest":"^26.5.6","typedoc":"^0.22.18","typescript":"^4.1.6","urllib":"^4.8.2"},"repository":{"type":"git","url":"git+https://github.com/aliyun/alicloud-httpdns-nodejs-sdk.git"},"bugs":{"url":"https://github.com/aliyun/alicloud-httpdns-nodejs-sdk/issues"},"homepage":"https://github.com/aliyun/alicloud-httpdns-nodejs-sdk","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_id":"@alicloud-emas/httpdns@1.0.0","gitHead":"d7ebb61e876e79e4963db0108bbb54c9a3769945","_nodeVersion":"24.3.0","_npmVersion":"11.4.2","dist":{"integrity":"sha512-8FNWfyNaEZtUX8yNfMNLhXQIf61IGu3gRtR5yFJ5lJLbxCFlT1+EwZRDp0JPZ08CI/+plFGF0+h45FYz3E2VnA==","shasum":"e4b017e57c6d57ef10371993481657b30ee3d7b5","tarball":"https://registry.npmjs.org/@alicloud-emas/httpdns/-/httpdns-1.0.0.tgz","fileCount":48,"unpackedSize":129939,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHTtP5aXneVeuFN687WM4fnEMLB0Bg98xqTXCkfZ/6UKAiEA0sK/HTiiWBqNlVra0X8tiG5geLOUDr3yX95+WNQd2T8="}]},"_npmUser":{"name":"zhongyujie","email":"zhongyujie.zyj@alibaba-inc.com"},"directories":{},"maintainers":[{"name":"yn_cr","email":"yannan.cr@alibaba-inc.com"},{"name":"zhongyujie","email":"zhongyujie.zyj@alibaba-inc.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/httpdns_1.0.0_1762851861264_0.6862756799556575"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-11T09:04:21.136Z","1.0.0":"2025-11-11T09:04:21.498Z","modified":"2025-11-11T09:04:21.843Z"},"maintainers":[{"name":"yn_cr","email":"yannan.cr@alibaba-inc.com"},{"name":"zhongyujie","email":"zhongyujie.zyj@alibaba-inc.com"}],"description":"阿里云EMAS HTTPDNS Node.js SDK - 通过HTTP/HTTPS协议提供高性能DNS解析服务","homepage":"https://github.com/aliyun/alicloud-httpdns-nodejs-sdk","keywords":["httpdns","dns","aliyun","alibaba","sdk","nodejs","typescript"],"repository":{"type":"git","url":"git+https://github.com/aliyun/alicloud-httpdns-nodejs-sdk.git"},"author":{"name":"Alibaba Cloud"},"bugs":{"url":"https://github.com/aliyun/alicloud-httpdns-nodejs-sdk/issues"},"license":"MIT","readme":"# HTTPDNS Node.js SDK\n\n[![Node.js Version](https://img.shields.io/badge/node-%3E%3D12.0.0-brightgreen.svg)](https://nodejs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-4.1%2B-blue.svg)](https://www.typescriptlang.org/)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n\n阿里云HTTPDNS Node.js SDK 是一个轻量级的 DNS 解析库，通过 HTTP/HTTPS 协议提供域名解析服务。支持阿里云 EMAS HTTPDNS 服务，为传统 DNS 解析提供更好的性能、安全性和可靠性。\n\n## 特性\n\n- ✅ **TypeScript优先**: 完整的TypeScript类型定义和类型安全\n- ✅ **版本兼容**: 支持Node.js 12+，兼容更广泛的用户群体\n- ✅ **高可用性**: 启动 IP 冗余、服务 IP 轮转、故障转移\n- ✅ **智能调度**: 支持客户端 IP 传递，实现就近接入\n- ✅ **安全认证**: 支持鉴权解析，MD5 签名算法\n- ✅ **性能优化**: 异步解析、连接复用、请求去重\n- ✅ **IPv6 支持**: 完整的 IPv4/IPv6 双栈支持\n\n## 安装\n\n```bash\nnpm install @alicloud-emas/httpdns\n```\n\n## 快速开始\n\n### 基础使用\n\n```typescript\nimport { createClient } from '@alicloud-emas/httpdns';\n\nasync function main() {\n  // 创建客户端\n  const client = createClient({\n    accountId: 'your-account-id'\n  });\n\n  try {\n    // 同步非阻塞解析域名（推荐方式）\n    const result = client.getHttpDnsResultForHostSyncNonBlocking('www.aliyun.com');\n    console.log('Domain:', result.domain);\n    console.log('IPv4:', result.ipv4);\n    console.log('IPv6:', result.ipv6);\n  } catch (error) {\n    console.error('Resolve failed:', error);\n  } finally {\n    // 关闭客户端\n    await client.close();\n  }\n}\n\nmain();\n```\n\n### 鉴权解析\n\n```typescript\n// 方式1: 使用createClient\nconst client = createClient({\n  accountId: 'your-account-id',\n  secretKey: 'your-secret-key'  // 启用鉴权解析\n});\n\n// 方式2: 使用便捷方法createHTTPDNSClient\nimport { createHTTPDNSClient } from '@alicloud-emas/httpdns';\n\nconst client = createHTTPDNSClient('your-account-id', 'your-secret-key');\n```\n\n### 同步非阻塞解析\n\n```typescript\n// 立即返回缓存结果或null，不阻塞\nconst cachedResult = client.getHttpDnsResultForHostSyncNonBlocking('www.aliyun.com');\n\nif (cachedResult) {\n  console.log('Cached result:', cachedResult.domain, '->', cachedResult.ipv4);\n} else {\n  console.log('No cached result, async resolution started');\n  \n  // 稍后再次查询可能已有缓存结果\n  setTimeout(() => {\n    const laterResult = client.getHttpDnsResultForHostSyncNonBlocking('www.aliyun.com');\n    if (laterResult) {\n      console.log('Later cached result:', laterResult.ipv4);\n    }\n  }, 1000);\n}\n```\n\n## 高级配置\n\n### 完整配置示例\n\n```typescript\nimport { createClient, QueryType } from '@alicloud-emas/httpdns';\n\nconst client = createClient({\n  // 认证信息\n  accountId: 'your-account-id',\n  secretKey: 'your-secret-key',\n  \n  // 网络配置\n  bootstrapIPs: ['203.107.1.1', '203.107.1.97'],\n  timeout: 5000,\n  maxRetries: 3,\n  \n  // 功能开关\n  enableHTTPS: false,\n  enableCache: true,\n  enableExpiredIP: true,  // 允许使用过期的缓存 IP\n  \n  // 日志配置\n  logger: console\n});\n```\n\n### 预解析域名\n\n```typescript\n// 创建客户端后设置预解析域名列表（最多100个）\nconst client = createClient({\n  accountId: 'your-account-id'\n});\n\n// 设置预解析列表，SDK 会在后台自动解析这些域名\nclient.setPreResolveHosts(['www.aliyun.com']);\n```\n\n### 允许使用过期 IP\n\n```typescript\n// 启用过期 IP 使用\nconst client = createClient({\n  accountId: 'your-account-id',\n  enableExpiredIP: true\n});\n```\n\n### 解析选项\n\n```typescript\n// 仅解析 IPv4\nconst result = client.getHttpDnsResultForHostSyncNonBlocking('www.aliyun.com', {\n  queryType: QueryType.IPv4\n});\n\n// 仅解析 IPv6\nconst result = client.getHttpDnsResultForHostSyncNonBlocking('www.aliyun.com', {\n  queryType: QueryType.IPv6\n});\n\n// 自定义超时\nconst result = client.getHttpDnsResultForHostSyncNonBlocking('www.aliyun.com', {\n  timeout: 10000\n});\n```\n\n## 客户端管理\n\n```typescript\n// 检查客户端健康状态\nconst isHealthy = client.isHealthy();\nconsole.log('Client is healthy:', isHealthy);\n\n// 获取当前服务IP列表\nconst serviceIPs = client.getServiceIPs();\nconsole.log('Service IPs:', serviceIPs);\n\n// 手动更新服务IP\nawait client.updateServiceIPs();\n```\n\n## 错误处理\n\n```typescript\nimport { HTTPDNSError } from '@alicloud-emas/httpdns';\n\ntry {\n  const result = client.getHttpDnsResultForHostSyncNonBlocking('www.aliyun.com');\n  if (!result) {\n    console.log('Resolve failed');\n  }\n} catch (error) {\n  if (error instanceof HTTPDNSError) {\n    console.log('Operation:', error.operation);\n    console.log('Domain:', error.domain);\n    console.log('Original Error:', error.originalError);\n  }\n}\n```\n\n## 开发\n\n### 构建\n\n```bash\nnpm run build\n```\n\n### 测试\n\n```bash\n# 运行所有测试\nnpm test\n\n# 运行测试并生成覆盖率报告\nnpm run test:coverage\n\n# 运行集成测试\nnpm run test:integration\n\n# 持续集成测试\nnpm run test:ci\n```\n\n### 代码质量\n\n```bash\n# 代码检查\nnpm run lint\n\n# 自动修复代码问题\nnpm run lint:fix\n\n# 代码格式化\nnpm run format\n\n# 检查代码格式\nnpm run format:check\n\n# TypeScript类型检查\nnpm run type-check\n\n# 完整验证（类型检查+构建）\nnpm run validate\n```\n\n## 许可证\n\n本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。\n\n## 贡献\n\n欢迎提交 Issue 和 Pull Request！\n\n## 更新日志\n\n详见 [CHANGELOG.md](CHANGELOG.md)","readmeFilename":"README.md","_rev":"1-c290581caaa3ebc5ac0d89b3bb22b257"}