init: 自 zomaintain/backend/rdplib 平移独立成库; module path 从上游 github.com/nakagami/grdp 改为 git.zeroonesoft.cn/golib/rdplib

2026-09-19 18:55:43 +08:00
commit 1096fbce9d
94 changed files with 36790 additions and 0 deletions
@@ -0,0 +1,119 @@
+# grdp — 纯 Go 的 RDP 客户端协议库
+
+本目录是可独立引用的 Go module `git.zeroonesoft.cn/golib/rdplib`（`github.com/nakagami/grdp` 的深度 fork，
+MIT 许可，保留上游版权），在 [nakagami/grdp](https://github.com/nakagami/grdp)
+（其 fork 自 [tomatome/grdp](https://github.com/tomatome/grdp)）基础上大幅扩展，
+是 [webrdp](../README.md) 浏览器客户端与原生诊断工具共用的协议栈。
+
+## 能力一览（fork 新增/重写部分加粗）
+
+- RDP 6.0+ 连接：**NLA/CredSSP(NTLMv2)**、TLS、标准安全协商
+- 图形：
+  - 传统位图/orders 管线（**位图缓存 V2/Memblt/指针形状**）
+  - **RDPGFX**（ClearCodec/RFX Progressive/Planar/AVC420/AVC444），
+    **H.264 以原始 NAL 或 I420/NV12 平面回调**交付（对接 WebCodecs/FFmpeg 均可）
+  - **动态分辨率**（DisplayControl 通道）与**会话色深**切换
+- 输入：扫描码键盘、**Unicode 文本输入**（中文 IME）、鼠标移动合并
+- 剪贴板：文本/图片/HTML/**文件复制**（含进度回调）
+- 音频：rdpsnd + AUDIO_PLAYBACK DVC，三模式（本地/远端/静音）
+- **驱动器重定向（rdpdr）**：宣告/验证/IO 编码、只读文件系统接口
+  （状态见 ../doc/RDPDR-2.md）
+- 连接期自动检测（RTT/带宽测量应答）、**并行 MCS 通道加入**、
+  服务器重定向 PDU 处理
+- **事件发射器 emission**：反射最小化 + 快速路径可摘除（有回归测试）
+- 诊断：PDU 录制器、GFX 缓存存储接口
+
+## 快速开始（原生 Go 调用）
+
+```go
+package main
+
+import (
+    "fmt"
+    "net"
+
+    "github.com/nakagami/grdp"
+)
+
+func main() {
+    client := grdp.NewRdpClient("10.0.0.3:3389", 1280, 800,
+        func(addr string) (net.Conn, error) { return net.Dial("tcp", addr) })
+
+    client.OnError(func(e error) { fmt.Println("err:", e) }).
+        OnClose(func() { fmt.Println("closed") }).
+        OnReady(func() { fmt.Println("session ready") }).
+        OnBitmap(func(bits []grdp.Bitmap) { /* RGBA() / FillRGBA(dst) */ }).
+        OnH264I420(func(x, y, w, h int, yb []byte, ys, u []byte, us, v []byte, vs int) {
+            // 送入渲染器/编码器
+        }).
+        OnClipboard(func(text string) { /* 远端剪贴板文本 */ }, func() string { return "" })
+
+    if err := client.Login("", "administrator", "password"); err != nil {
+        panic(err)
+    }
+    // 输入/分辨率/关闭：
+    // client.SendUnicodeText("你好"); client.SetResolution(1920, 1080); client.Close()
+    select {}
+}
+```
+
+完整可运行示例：仓库上层 `cmd/nativedemo`（带带宽/编码统计的诊断客户端，
+`go run ./cmd/nativedemo -host x -user u -pass p`）。
+浏览器（WASM/WebSocket）宿主实现：仓库上层根目录 `main.go` + `wasm_transport.go`。
+
+回调都在协议栈读循环 goroutine 内触发——回调里不要长时间阻塞，
+重活请转交自己的 goroutine。
+
+## 架构
+
+```
+grdp.RdpClient                    门户：配置(链式 Set*/On*) + Login + 生命周期
+├─ protocol/x224·tpkt·t125·sec    传输/安全层（MCS 通道、加密；NLA 在 protocol/nla）
+├─ protocol/pdu·lic·gcc           虚拟桌面 PDU、能力协商、许可、GCC
+├─ plugin/                        虚拟通道框架 + 内置通道
+│   ├─ Channels.Register(ChannelTransport)   通道注册
+│   └─ rdpsnd cliprdr rdpdr rdpgfx rdpedisp drdynvc
+├─ core/                          传输抽象、缓冲池、工具
+└─ emission/                      事件发射器
+```
+
+自定义虚拟通道只需实现三个方法（见 `plugin/channel.go`）：
+
+```go
+type ChannelTransport interface {
+    GetType() (string, uint32)          // 通道名 + CHANNEL_OPTION_*
+    Sender(core.ChannelSender)          // 栈回调的发送器
+    Process(s []byte)                   // 收包
+}
+```
+
+## 构建与测试
+
+```
+go build ./...     # 普通 GOOS 即可；WASM 用 GOOS=js GOARCH=wasm
+go test ./...
+```
+
+FFmpeg 硬解（可选）：`-tags h264`，依赖 libavcodec ≥3.4（macOS VideoToolbox /
+Linux VAAPI 自动启用，软件回退）。纯 Go 构建默认不带 AVC 解码
+（但保留 AVC 能力协商与 NAL 回调，解码交给宿主，如浏览器的 WebCodecs）。
+
+## 发布检查单（fork 注意事项）
+
+- 模块路径当前沿用上游 `github.com/nakagami/grdp`（可离线构建、自主维护，
+  经上层 go.mod `replace` 引用）。**对外发布前需改为你自己的 module path**：
+  改本目录 `go.mod` 的 module 行 + 全部 import 前缀
+  （`sed -i 's|github.com/nakagami/grdp|<你的路径>|g'`），与上层仓库无其他耦合。
+- 许可证 MIT，上游版权声明见 LICENSE，请保留。
+- 已知问题：驱动器重定向在部分 Windows 服务端上被关闭（RDPDR-2），
+  跟踪见 ../doc/RDPDR-2.md。
+
+## 上游致谢与相关项目
+
+- 上游取材：[rdpy](https://github.com/citronneur/rdpy)、
+  [node-rdpjs](https://github.com/citronneur/node-rdpjs)、
+  [gordp](https://github.com/Madnikulin50/gordp)、
+  [ncrack_rdp](https://github.com/nmap/ncrack/blob/master/modules/ncrack_rdp.cc)、
+  [webRDP](https://github.com/Chorder/webRDP)
+- 相关：https://github.com/nakagami/grdpsdl2 、
+  https://github.com/nakagami/grdpwasm