#MoonDiscover

#项目作用

#解决什么问题

• mDNS：在本地链路上使用组播传递 DNS 查询和响应。
• DNS-SD：通过 PTR、SRV、TXT 等记录描述服务实例、端点与属性。
• MoonDiscover：实现本项目支持的报文处理、TTL 缓存、服务聚合、查询调度和事件生命周期；Native 层负责真实网络收发。

#适合哪些场景

#工作方式

flowchart LR
  P[局域网中已有的服务发布者] <-->|IPv4 mDNS 组播| N[Native Browser]
  N <--> E[纯 MoonBit Engine]
  E --> S[快照与生命周期事件]
  S --> A[你的应用或 CLI]
  N --> T[JSONL 录制]
  T --> R[离线 Replay]
  R --> E

#版本选择

#安装与构建

#在已有 MoonBit 工程中安装发布包

moon add mik1e80/dnssd@0.2.0

#获取开发源码

git clone https://github.com/mik1e80/MoonDiscover.git moondiscover
cd moondiscover

#Windows / PowerShell

.\scripts\bootstrap.ps1
.\scripts\moon.ps1 run examples/encode_query --target js --frozen
.\scripts\moon.ps1 build cmd/moondiscover --target native --frozen

_build/native/debug/build/cmd/moondiscover/moondiscover.exe

#Linux

curl -fsSL https://cli.moonbitlang.com/install/unix.sh | bash -s -- '0.10.17+d971670cd'
export PATH="$HOME/.moon/bin:$PATH"
moon update
moon build cmd/moondiscover --target native --frozen
./_build/native/debug/build/cmd/moondiscover/moondiscover --help

#命令行使用

$cli = '.\_build\native\debug\build\cmd\moondiscover\moondiscover.exe'
& $cli --help
& $cli --version

#1. 检查本机接口和共享绑定

& $cli doctor --interface 192.168.1.10

#2. 浏览指定类型

& $cli browse --interface 192.168.1.10 --service _http._tcp.local. --duration-ms 5000

& $cli browse --interface 192.168.1.10 --service '_http._tcp.local.,_ipp._tcp.local.' --duration-ms 10000

& $cli browse --interface 192.168.1.10 --service _printer._sub._http._tcp.local. --duration-ms 5000

#3. 解析已知实例

& $cli resolve --interface 192.168.1.10 --instance 'Demo._http._tcp.local.' --duration-ms 5000

#4. 录制与离线回放

& $cli browse --interface 192.168.1.10 --service _http._tcp.local. --duration-ms 5000 --record trace.jsonl
& $cli replay --file trace.jsonl

& $cli replay --file fixtures/live-20261024.jsonl

#5. 理解 JSONL 输出

#作为库使用

#纯核心：无需网络的最小例子

import {
  "mik1e80/dnssd",
}

pkgtype(kind: "executable")

fn main raise {
  let name = @dnssd.DnsName::from_utf8_labels(["_http", "_tcp", "local"])
  let packet = @dnssd.qm_query(name, 12)
  let decoded = @dnssd.decode_packet(packet)
  println(
    "QM PTR query: \{decoded.questions[0].name.to_presentation()} (\{packet.length()} bytes)",
  )
}

#Native：订阅真实网络事件

async fn main {
  let args = @env.args()
  guard args.length() == 3 else {
    fail("usage: watch_events <interface-ipv4> <service-type>")
  }
  let interface = @socket.Addr::parse(args[1] + ":0")
  guard !interface.is_ipv6() else { fail("IPv4 required") }
  let browser = @native.Browser::open(interface.ip())
  defer browser.close()
  let _ = browser.browse(@dnssd.DnsName::parse(args[2]))
  browser.run(5000, event => {
    @stdio.stdout.write(@dnssd.event_json(event).stringify() + "\n")
  })
}

.\scripts\moon.ps1 run examples/watch_events --target native --frozen -- 192.168.1.10 _http._tcp.local.

#自行集成 Engine

1. 创建 Engine，设置所需容量和随机种子。
2. 调用 browse 或 resolve，提供明确 scope 和单调 Int64 毫秒时间。
3. 用 ingest 输入收包；按 next_deadline() 推进 advance，没有收包时也要处理定时器。
4. 取尽 poll_outbound()，连续发送到对应 scope；Known-Answer 分包整组发完后再改变输入或时间。
5. 取事件、读取 snapshots()；取消或结束时调用 cancel / close。

#在浏览器离线查看录制

.\scripts\build-replay.ps1
python -m http.server 8000 --bind 127.0.0.1 --directory .tools/browser-replay

#使用边界

#网络与协议

#数据与资源上限

#发现结果的含义

• complete=true 表示当前缓存记录链满足本实现要求，不代表目标一定可连接、HTTP 请求成功或设备身份可信。
• TTL 到期表示缓存证据失效；观察窗口无结果表示该窗口未发现，不能直接等同设备离线。
• 名称保留原始标签及标签内的点，仅折叠 ASCII 大小写。构造实例时优先传入已划分标签，不要机械按点拆展示名。
• TXT 可能包含二进制；JSON 十六进制保留原条目，应用仍应校验自己使用的键和值。
• 同 scope 的多个订阅共享身份；跨 scope 同名实例独立，应用应连同 scope 标识列表项。
• 连接认证、访问控制、重试和超时由业务应用负责。HTTP 示例的 demo token 仅作受控测试筛选，不是身份认证。

#平台与证据范围

#常见问题

#验证与文档

.\scripts\moon.ps1 test src/wire/known_answer_limits_test.mbt src/engine/known_answer_fallback_test.mbt src/engine/query_invalid_wbtest.mbt src/replay/replay_test.mbt --target js --frozen --filter 'smoke:*'