eric/terminalX
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

初始提交：terminalX 可运行态（M0/M1/M1.5 已真机验证）

Browse Source 
- M0: libghostty SSH 终端（渲染/输入/连接）+ 白屏修复(OutputGate) + 会话状态机/自动重连
- M1: tsnet 用户态组网 + SSH-over-tsnet(fd 桥)，shell 级真机验证；R5(Go+gvisor+C+++Swift 同进程) retire
- M1.5: tmux -CC 原生 tab（MVP）
- 结构: packages/(TXCore·TXTransport), apps/TerminalX, vendor/(libghostty-spm/libssh2/mbedtls/tsnet-bridge), artifacts/
- 文档: CLAUDE.md + docs/HANDOFF.md（新会话入口）
- 环境: 认证代理→依赖 vendor 本地化；Go 在 ~/.local/go；仅模拟器/未签名
- 待续: M2 mosh, tmux 多 pane, M4 安全(host key/SE)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
kid
2026-07-24 10:20:46 +08:00
commit aa92d0e676
2761 changed files with 803505 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
packages/TXCore/Package.swift Normal file
View File

@@ -0,0 +1,25 @@
// swift-tools-version: 6.0
import PackageDescription
let package = Package(
name: "TXCore",
platforms: [
.macOS(.v14),
.iOS(.v17),
],
products: [
.library(name: "TXCore", targets: ["TXCore"]),
],
targets: [
// 零依赖：领域模型、状态机、协议、纯算法。可在 macOS 命令行 `swift test`。
.target(
name: "TXCore",
swiftSettings: [.swiftLanguageMode(.v6)]
),
.testTarget(
name: "TXCoreTests",
dependencies: ["TXCore"],
swiftSettings: [.swiftLanguageMode(.v6)]
),
]
)

164
packages/TXCore/Sources/TXCore/Session/SessionMachine.swift Normal file
View File

@@ -0,0 +1,164 @@
import Foundation
/// 会话生命周期状态机（切片② + M3 地基）。纯逻辑、零依赖、可单测。
///
/// 设计要点：`reduce(event)` 是纯函数式转移——输入事件、更新 `phase`、返回一组
/// `Effect`（副作用意图）由外层执行（发起连接、排程重连、更新 UI 等）。
/// 移动端核心诉求：断线/失败后按指数退避自动重连，前台恢复即重试。
public struct SessionMachine: Sendable, Equatable {
public enum Phase: Sendable, Equatable {
case idle
case connecting
case authenticating
case connected
/// 进入后台，连接冻结（保留最后画面），不主动断开。
case backgroundParked
/// 已断开/失败，等待下一次自动重连（记录第几次尝试）。
case waitingToReconnect(attempt: Int)
/// 正在执行自动重连。
case reconnecting(attempt: Int)
/// 终态失败：需要用户介入（认证失效等），不再自动重连。
case failed(reason: String)
/// 用户主动关闭。
case closed
}
public enum Event: Sendable, Equatable {
case connectRequested
case authenticating
case established // 传输层报告已连接
case transportClosed(reason: String?) // 网络断开（可重连）
case authFailed(reason: String) // 认证失败（终态，不重连）
case reconnectTimerFired
case enteredBackground
case enteredForeground
case closeRequested
case retryRequested // 用户手动重试（从 failed 复位）
}
public enum Effect: Sendable, Equatable {
case startConnect
case scheduleReconnect(attempt: Int, delayMS: Int)
case cancelReconnectTimer
case teardownTransport
case notify(String) // UI 提示
}
public private(set) var phase: Phase = .idle
/// 最大自动重连次数（超过则转 failed）。
public let maxReconnectAttempts: Int
/// 退避基数与上限（毫秒）。
private let baseDelayMS: Int
private let maxDelayMS: Int
public init(maxReconnectAttempts: Int = 6, baseDelayMS: Int = 500, maxDelayMS: Int = 16000) {
self.maxReconnectAttempts = maxReconnectAttempts
self.baseDelayMS = baseDelayMS
self.maxDelayMS = maxDelayMS
}
/// 指数退避：base * 2^(attempt-1)，封顶 maxDelayMS。
public func backoffDelayMS(attempt: Int) -> Int {
guard attempt >= 1 else { return baseDelayMS }
let shift = min(attempt - 1, 30)
let raw = baseDelayMS * (1 << shift)
return min(raw, maxDelayMS)
}
/// 处理一个事件，就地更新 phase，返回需执行的副作用。
public mutating func reduce(_ event: Event) -> [Effect] {
switch (phase, event) {
// —— 发起连接 ——
case (.idle, .connectRequested),
(.closed, .connectRequested),
(.failed, .retryRequested):
phase = .connecting
return [.startConnect]
case (.connecting, .authenticating):
phase = .authenticating
return []
case (.connecting, .established), (.authenticating, .established):
phase = .connected
return [.notify("已连接")]
// —— 认证失败：终态，不自动重连 ——
case (.connecting, .authFailed(let r)), (.authenticating, .authFailed(let r)):
phase = .failed(reason: r)
return [.teardownTransport, .notify("认证失败：\(r)")]
// —— 网络断开：进入自动重连（从已连接或连接中）——
case (.connected, .transportClosed(let r)),
(.connecting, .transportClosed(let r)),
(.authenticating, .transportClosed(let r)):
return enterReconnect(fromAttempt: 0, reason: r)
// —— 重连计时到点：执行重连 ——
case (.waitingToReconnect(let attempt), .reconnectTimerFired):
phase = .reconnecting(attempt: attempt)
return [.startConnect]
// 重连成功
case (.reconnecting, .established):
phase = .connected
return [.notify("已重连")]
// 重连中的过渡态
case (.reconnecting, .authenticating):
return []
case (.reconnecting, .authFailed(let r)):
phase = .failed(reason: r)
return [.teardownTransport, .notify("认证失败：\(r)")]
// 重连又断：下一次退避（attempt 递增）
case (.reconnecting(let attempt), .transportClosed(let r)):
return enterReconnect(fromAttempt: attempt, reason: r)
// —— 后台/前台 ——
case (.connected, .enteredBackground):
phase = .backgroundParked
return []
case (.backgroundParked, .enteredForeground):
// 恢复：主动触发一次重连探测（attempt 从 1 起）
phase = .reconnecting(attempt: 1)
return [.startConnect, .notify("恢复中…")]
case (.backgroundParked, .transportClosed):
// 后台期间底层已断，回前台会重连；保持 parked
return []
// 等待重连期间进入后台：取消计时，parked
case (.waitingToReconnect, .enteredBackground):
phase = .backgroundParked
return [.cancelReconnectTimer]
// —— 关闭 ——
case (_, .closeRequested):
phase = .closed
return [.cancelReconnectTimer, .teardownTransport]
// 其它组合不改变状态
default:
return []
}
}
private mutating func enterReconnect(fromAttempt: Int, reason: String?) -> [Effect] {
let next = fromAttempt + 1
if next > maxReconnectAttempts {
phase = .failed(reason: reason ?? "连接中断，重连已达上限")
return [.teardownTransport, .notify("重连失败，请手动重试")]
}
phase = .waitingToReconnect(attempt: next)
let delay = backoffDelayMS(attempt: next)
let reasonText = reason.map { "：\($0)" } ?? ""
return [
.teardownTransport,
.scheduleReconnect(attempt: next, delayMS: delay),
.notify("连接中断\(reasonText)，\(delay / 1000)s 后重连（第 \(next) 次）"),
]
}
}

203
packages/TXCore/Sources/TXCore/Tmux/TmuxControlParser.swift Normal file
View File

@@ -0,0 +1,203 @@
import Foundation
/// tmux control-mode 行协议解析器。
///
/// 输入任意切片的字节流（`feed`），输出完整语义事件。**不涉及 UI、非 `@MainActor`**，
/// 设计为在 transport 的串行队列上运行。
///
/// 关键不变量（依据协议）：
/// - 输出严格按行（`\n`），残行缓冲到下次 `feed`；容忍 `\r\n`。
/// - `%begin`…`%end`/`%error` 守卫块之间的所有行都是命令输出，**即使以 `%` 开头**也不解释为通知。
/// - `%output` payload 按字节八进制解码，绝不经 `String`（UTF-8 多字节字符可能跨多条 `%output`）。
/// - 未知 `%`-行降级为 `.unknown`，保证前向兼容。
public final class TmuxControlParser {
private enum State {
case idle
case inBlock(number: Int, lines: [String])
}
private var buffer: [UInt8] = []
private var state: State = .idle
public init() {}
/// 送入一段原始字节，返回本次可解析出的完整事件（可能为空）。
public func feed(_ chunk: Data) -> [TmuxEvent] {
buffer.append(contentsOf: chunk)
var events: [TmuxEvent] = []
while let nl = buffer.firstIndex(of: 0x0A) {
var line = Array(buffer[buffer.startIndex..<nl])
buffer.removeSubrange(buffer.startIndex...nl)
if line.last == 0x0D { line.removeLast() } // 容忍 CRLF
handle(line: line, into: &events)
}
return events
}
/// 字符串便捷入口（测试用）。
public func feed(_ text: String) -> [TmuxEvent] {
feed(Data(text.utf8))
}
// MARK: - 行处理
private func handle(line: [UInt8], into events: inout [TmuxEvent]) {
switch state {
case .inBlock(let number, var lines):
if let guardLine = parseBlockGuard(line), guardLine.number == number {
events.append(.commandResponse(
TmuxCommandResponse(number: number, isError: guardLine.isError, lines: lines)
))
state = .idle
} else {
lines.append(String(decoding: line, as: UTF8.self))
state = .inBlock(number: number, lines: lines)
}
case .idle:
if line.first == 0x25 /* % */ {
if let begin = parseBeginGuard(line) {
state = .inBlock(number: begin, lines: [])
} else {
parseNotification(line: line, into: &events)
}
} else {
// idle 态下的非 %-行属于协议噪声（如登录横幅）。
events.append(.unknown(line: String(decoding: line, as: UTF8.self)))
}
}
}
// MARK: - 守卫行
/// `%begin <time> <number> <flags>` → number
private func parseBeginGuard(_ line: [UInt8]) -> Int? {
let tokens = tokenize(line)
guard tokens.first == "%begin", tokens.count >= 3 else { return nil }
return Int(tokens[2])
}
/// `%end|%error <time> <number> <flags>`
private func parseBlockGuard(_ line: [UInt8]) -> (number: Int, isError: Bool)? {
let tokens = tokenize(line)
guard let head = tokens.first, head == "%end" || head == "%error",
tokens.count >= 3, let n = Int(tokens[2]) else { return nil }
return (n, head == "%error")
}
// MARK: - 通知
private func parseNotification(line: [UInt8], into events: inout [TmuxEvent]) {
let tokens = tokenize(line)
guard let head = tokens.first else {
events.append(.unknown(line: String(decoding: line, as: UTF8.self)))
return
}
switch head {
case "%output":
// %output %<pane> <data>；data 从第 2 个空格后取原始字节（含 raw space）。
guard tokens.count >= 2, let pane = TmuxPaneID.parse(tokens[1]) else { break }
let payload = TmuxOutputDecoder.decode(bytesAfterTokens(2, in: line))
events.append(.output(pane: pane, data: payload))
return
case "%extended-output":
// %extended-output %<pane> <age> : <data>
guard tokens.count >= 4, let pane = TmuxPaneID.parse(tokens[1]),
let age = Int(tokens[2]) else { break }
// tokens[3] 为 ":"；data 从第 4 个空格后取。
let payload = TmuxOutputDecoder.decode(bytesAfterTokens(4, in: line))
events.append(.extendedOutput(pane: pane, ageMS: age, data: payload))
return
case "%window-add":
if tokens.count >= 2, let w = TmuxWindowID.parse(tokens[1]) {
events.append(.windowAdd(w)); return
}
case "%window-close":
if tokens.count >= 2, let w = TmuxWindowID.parse(tokens[1]) {
events.append(.windowClose(w)); return
}
case "%unlinked-window-close":
if tokens.count >= 2, let w = TmuxWindowID.parse(tokens[1]) {
events.append(.unlinkedWindowClose(w)); return
}
case "%window-renamed":
if tokens.count >= 3, let w = TmuxWindowID.parse(tokens[1]) {
events.append(.windowRenamed(w, name: tokens[2...].joined(separator: " "))); return
}
case "%window-pane-changed":
if tokens.count >= 3, let w = TmuxWindowID.parse(tokens[1]),
let p = TmuxPaneID.parse(tokens[2]) {
events.append(.windowPaneChanged(window: w, pane: p)); return
}
case "%layout-change":
// %layout-change @<w> <layout> [<visible-layout>] [<flags>]
if tokens.count >= 3, let w = TmuxWindowID.parse(tokens[1]) {
let visible = tokens.count >= 4 ? tokens[3] : nil
events.append(.layoutChange(window: w, layout: tokens[2], visibleLayout: visible)); return
}
case "%session-changed":
if tokens.count >= 3, let s = TmuxSessionID.parse(tokens[1]) {
events.append(.sessionChanged(s, name: tokens[2...].joined(separator: " "))); return
}
case "%session-renamed":
// 部分版本为 `%session-renamed <name>`（当前会话），也有带 $id 的形式；两者都容忍。
if tokens.count >= 3, let s = TmuxSessionID.parse(tokens[1]) {
events.append(.sessionRenamed(s, name: tokens[2...].joined(separator: " "))); return
}
case "%sessions-changed":
events.append(.sessionsChanged); return
case "%session-window-changed":
if tokens.count >= 3, let s = TmuxSessionID.parse(tokens[1]),
let w = TmuxWindowID.parse(tokens[2]) {
events.append(.sessionWindowChanged(session: s, window: w)); return
}
case "%pane-mode-changed":
if tokens.count >= 2, let p = TmuxPaneID.parse(tokens[1]) {
events.append(.paneModeChanged(p)); return
}
case "%pause":
if tokens.count >= 2, let p = TmuxPaneID.parse(tokens[1]) {
events.append(.pause(p)); return
}
case "%continue":
if tokens.count >= 2, let p = TmuxPaneID.parse(tokens[1]) {
events.append(.unpause(p)); return
}
case "%exit":
let reason = tokens.count >= 2 ? tokens[1...].joined(separator: " ") : nil
events.append(.exit(reason: reason)); return
default:
break
}
events.append(.unknown(line: String(decoding: line, as: UTF8.self)))
}
// MARK: - 字节级辅助
/// 按 ASCII 空格切分为 UTF-8 字符串 token（用于守卫行/通知头，非 payload）。
private func tokenize(_ line: [UInt8]) -> [String] {
line.split(separator: 0x20, omittingEmptySubsequences: true)
.map { String(decoding: $0, as: UTF8.self) }
}
/// 返回跳过前 `n` 个以空格分隔的 token 之后的原始字节切片（保留 payload 内的 raw space）。
private func bytesAfterTokens(_ n: Int, in line: [UInt8]) -> ArraySlice<UInt8> {
var idx = line.startIndex
var spacesSeen = 0
// 逐字节推进，跳过 n 段非空格 + 其后的单个分隔空格。
while idx < line.endIndex && spacesSeen < n {
// 跳过一个 token（非空格）
while idx < line.endIndex && line[idx] != 0x20 { idx = line.index(after: idx) }
// 跳过分隔空格
if idx < line.endIndex { idx = line.index(after: idx) }
spacesSeen += 1
}
return line[idx..<line.endIndex]
}
}

41
packages/TXCore/Sources/TXCore/Tmux/TmuxControlSequence.swift Normal file
View File

@@ -0,0 +1,41 @@
import Foundation
/// tmux `-CC`（iTerm2 风格）控制模式的进入/退出哨兵序列检测。
/// 进入：tmux 打印 DCS `ESC P 1000 p`；退出：`%exit` 后打印 ST `ESC \`。
/// 用于在原始字节流中把「普通 shell 输出」与「control-mode 协议流」分界。
public enum TmuxControlSequence {
/// 进入控制模式的 DCS：ESC P 1000 p
public static let enter: [UInt8] = [0x1B, 0x50, 0x31, 0x30, 0x30, 0x30, 0x70]
/// 退出控制模式的 ST：ESC \
public static let exit: [UInt8] = [0x1B, 0x5C]
/// 在 bytes 中查找 needle，返回其**起始**下标；未找到返回 nil。
public static func find(_ needle: [UInt8], in bytes: [UInt8]) -> Int? {
guard !needle.isEmpty, bytes.count >= needle.count else { return nil }
let last = bytes.count - needle.count
var i = 0
while i <= last {
var j = 0
while j < needle.count && bytes[i + j] == needle[j] { j += 1 }
if j == needle.count { return i }
i += 1
}
return nil
}
/// 为「跨 feed 边界」的哨兵匹配保留的尾部长度（needle 最长 - 1）。
public static var maxSentinelTail: Int { max(enter.count, exit.count) - 1 }
/// 返回 bytes 尾部与 needle 前缀相同的最大长度（1..<needle.count）；无则 0。
/// 用于仅在「chunk 结尾恰是哨兵的部分前缀」时才滞留字节，避免延迟正常输出。
public static func partialTrailingMatchLength(_ needle: [UInt8], in bytes: [UInt8]) -> Int {
var k = min(needle.count - 1, bytes.count)
while k > 0 {
var match = true
for j in 0 ..< k where bytes[bytes.count - k + j] != needle[j] { match = false; break }
if match { return k }
k -= 1
}
return 0
}
}

60
packages/TXCore/Sources/TXCore/Tmux/TmuxEvent.swift Normal file
View File

@@ -0,0 +1,60 @@
import Foundation
/// control-mode 解析器输出的语义事件。
///
/// 协议参考：https://github.com/tmux/tmux/wiki/Control-Mode
/// - `%output`/`%extended-output` 承载 pane 的原始 PTY 字节（已从八进制转义还原为 `Data`）。
/// - 命令应答由 `%begin`/`%end`/`%error` 守卫块包裹，按命令发送顺序返回。
/// - 其余 `%`-前缀行是异步通知。
public enum TmuxEvent: Sendable, Equatable {
/// `%output %<pane> <data>` — pane 的 PTY 输出（已解码为原始字节）。
case output(pane: TmuxPaneID, data: Data)
/// `%extended-output %<pane> <age-ms> : <data>` — 带滞后毫秒数的输出（流控场景）。
case extendedOutput(pane: TmuxPaneID, ageMS: Int, data: Data)
/// 一条命令的完整应答（`%begin`…`%end`/`%error` 之间）。
case commandResponse(TmuxCommandResponse)
case windowAdd(TmuxWindowID)
case windowClose(TmuxWindowID)
case unlinkedWindowClose(TmuxWindowID)
case windowRenamed(TmuxWindowID, name: String)
case windowPaneChanged(window: TmuxWindowID, pane: TmuxPaneID)
case layoutChange(window: TmuxWindowID, layout: String, visibleLayout: String?)
case sessionChanged(TmuxSessionID, name: String)
case sessionRenamed(TmuxSessionID, name: String)
case sessionsChanged
case sessionWindowChanged(session: TmuxSessionID, window: TmuxWindowID)
case paneModeChanged(TmuxPaneID)
/// 流控：某 pane 输出被暂停 / 恢复。
case pause(TmuxPaneID)
case unpause(TmuxPaneID)
case exit(reason: String?)
/// 前向兼容：未识别的行（未知通知或协议噪声）。上层应容忍并记录。
case unknown(line: String)
}
/// `%begin <t> <num> <flags>` … `%end|%error <t> <num> <flags>` 之间的原始输出。
public struct TmuxCommandResponse: Sendable, Equatable {
/// 命令序号（守卫行的第 2 个字段），用于与发送队列 FIFO 关联。
public let number: Int
/// 是否以 `%error` 结束。
public let isError: Bool
/// 守卫块内的原始行（不含守卫行本身）。
public let lines: [String]
public init(number: Int, isError: Bool, lines: [String]) {
self.number = number
self.isError = isError
self.lines = lines
}
/// 便捷：整块合并为字符串。
public var text: String { lines.joined(separator: "\n") }
}

42
packages/TXCore/Sources/TXCore/Tmux/TmuxIDs.swift Normal file
View File

@@ -0,0 +1,42 @@
import Foundation
/// tmux 对象标识。control mode 里以带前缀的十进制文本出现：
/// pane `%3`、window `@2`、session `$1`。
public struct TmuxPaneID: Hashable, Sendable, CustomStringConvertible {
public let raw: Int
public init(_ raw: Int) { self.raw = raw }
public var description: String { "%\(raw)" }
/// 解析 `%3` → TmuxPaneID(3)。前缀不符或非数字返回 nil。
public static func parse(_ token: some StringProtocol) -> TmuxPaneID? {
TmuxID.parse(token, prefix: "%").map(TmuxPaneID.init)
}
}
public struct TmuxWindowID: Hashable, Sendable, CustomStringConvertible {
public let raw: Int
public init(_ raw: Int) { self.raw = raw }
public var description: String { "@\(raw)" }
public static func parse(_ token: some StringProtocol) -> TmuxWindowID? {
TmuxID.parse(token, prefix: "@").map(TmuxWindowID.init)
}
}
public struct TmuxSessionID: Hashable, Sendable, CustomStringConvertible {
public let raw: Int
public init(_ raw: Int) { self.raw = raw }
public var description: String { "$\(raw)" }
public static func parse(_ token: some StringProtocol) -> TmuxSessionID? {
TmuxID.parse(token, prefix: "$").map(TmuxSessionID.init)
}
}
enum TmuxID {
/// 校验前缀并解析其后的十进制整数。
static func parse(_ token: some StringProtocol, prefix: Character) -> Int? {
guard let first = token.first, first == prefix else { return nil }
return Int(token.dropFirst())
}
}

127
packages/TXCore/Sources/TXCore/Tmux/TmuxLayout.swift Normal file
View File

@@ -0,0 +1,127 @@
import Foundation
/// tmux window layout 字符串的解析结果。
///
/// 格式（递归）：`<csum>,<cell>`，其中
/// - `cell` = `WxH,X,Y` 后接三选一：`,<paneId>`（叶子）、`{c,c,…}`（左右并列）、`[c,c,…]`（上下并列）。
/// - 前导 `<csum>` 是 4 位十六进制校验和，解析时忽略。
///
/// 例：`bc62,80x24,0,0,0`（单 pane）、
/// `a1b2,80x24,0,0{40x24,0,0,1,39x24,41,0,2}`（两 pane 左右分屏）。
public struct TmuxLayout: Sendable, Equatable {
public let root: Node
public indirect enum Node: Sendable, Equatable {
case leaf(pane: TmuxPaneID, rect: Rect)
/// 子节点沿水平方向并排（`{}`）。
case horizontal([Node], rect: Rect)
/// 子节点沿垂直方向堆叠（`[]`）。
case vertical([Node], rect: Rect)
public var rect: Rect {
switch self {
case .leaf(_, let r), .horizontal(_, let r), .vertical(_, let r): return r
}
}
}
public struct Rect: Sendable, Equatable {
public let width: Int, height: Int, x: Int, y: Int
public init(width: Int, height: Int, x: Int, y: Int) {
self.width = width; self.height = height; self.x = x; self.y = y
}
}
public enum ParseError: Error, Equatable {
case empty
case malformed(at: Int, reason: String)
case trailingGarbage(at: Int)
}
/// 收集 layout 中出现的全部 pane（用于与现有 pane 集合做 diff）。
public var paneIDs: [TmuxPaneID] {
var acc: [TmuxPaneID] = []
func walk(_ n: Node) {
switch n {
case .leaf(let p, _): acc.append(p)
case .horizontal(let cs, _), .vertical(let cs, _): cs.forEach(walk)
}
}
walk(root)
return acc
}
public static func parse(_ s: String) throws -> TmuxLayout {
guard let comma = s.firstIndex(of: ",") else { throw ParseError.empty }
let body = s[s.index(after: comma)...]
var cur = Cursor(Array(body))
let root = try cur.parseCell()
guard cur.isAtEnd else { throw ParseError.trailingGarbage(at: cur.offset) }
return TmuxLayout(root: root)
}
}
private struct Cursor {
let chars: [Character]
var i = 0
init(_ chars: [Character]) { self.chars = chars }
var isAtEnd: Bool { i >= chars.count }
var offset: Int { i }
private func peek() -> Character? { i < chars.count ? chars[i] : nil }
mutating func parseCell() throws -> TmuxLayout.Node {
let start = i
let w = try parseInt()
try expect("x")
let h = try parseInt()
try expect(",")
let x = try parseInt()
try expect(",")
let y = try parseInt()
let rect = TmuxLayout.Rect(width: w, height: h, x: x, y: y)
switch peek() {
case "{":
let children = try parseChildren(open: "{", close: "}")
return .horizontal(children, rect: rect)
case "[":
let children = try parseChildren(open: "[", close: "]")
return .vertical(children, rect: rect)
case ",":
i += 1
let paneRaw = try parseInt()
return .leaf(pane: TmuxPaneID(paneRaw), rect: rect)
default:
throw TmuxLayout.ParseError.malformed(at: start, reason: "cell 缺少 pane id 或子节点")
}
}
private mutating func parseChildren(open: Character, close: Character) throws -> [TmuxLayout.Node] {
try expect(open)
var nodes: [TmuxLayout.Node] = []
while true {
nodes.append(try parseCell())
if peek() == "," { i += 1; continue }
break
}
try expect(close)
return nodes
}
private mutating func parseInt() throws -> Int {
let start = i
while let c = peek(), c.isNumber { i += 1 }
guard i > start, let v = Int(String(chars[start..<i])) else {
throw TmuxLayout.ParseError.malformed(at: start, reason: "期望数字")
}
return v
}
private mutating func expect(_ c: Character) throws {
guard peek() == c else {
throw TmuxLayout.ParseError.malformed(at: i, reason: "期望 '\(c)'")
}
i += 1
}
}

46
packages/TXCore/Sources/TXCore/Tmux/TmuxOutputDecoder.swift Normal file
View File

@@ -0,0 +1,46 @@
import Foundation
/// `%output` 的 payload 转义还原。
///
/// tmux 在 control mode 下对 pane 输出中 **ASCII < 32 的字节与反斜杠本身**
/// 用三位八进制转义（`\ooo`），其余字节（含空格 0x20）原样传输。
/// 例：换行 `\n`(0x0A) → `\012`，反斜杠 `\`(0x5C) → `\134`。
enum TmuxOutputDecoder {
/// 将转义态字节还原为原始字节。非法/不完整的 `\` 序列按原样保留（稳健优先）。
static func decode(_ bytes: ArraySlice<UInt8>) -> Data {
var out = [UInt8]()
out.reserveCapacity(bytes.count)
var i = bytes.startIndex
let end = bytes.endIndex
while i < end {
let b = bytes[i]
guard b == 0x5C /* backslash */ else {
out.append(b)
i = bytes.index(after: i)
continue
}
// 需要其后正好三位八进制数字（0-7）。
let d0 = bytes.index(i, offsetBy: 1, limitedBy: end) ?? end
let d1 = bytes.index(i, offsetBy: 2, limitedBy: end) ?? end
let d2 = bytes.index(i, offsetBy: 3, limitedBy: end) ?? end
if d2 < end,
let v0 = octalValue(bytes[d0]),
let v1 = octalValue(bytes[d1]),
let v2 = octalValue(bytes[d2]) {
out.append(UInt8(v0 * 64 + v1 * 8 + v2))
i = bytes.index(i, offsetBy: 4)
} else {
// 不是合法八进制转义，原样保留反斜杠。
out.append(b)
i = bytes.index(after: i)
}
}
return Data(out)
}
private static func octalValue(_ b: UInt8) -> Int? {
(0x30...0x37).contains(b) ? Int(b - 0x30) : nil
}
}

128
packages/TXCore/Tests/TXCoreTests/SessionMachineTests.swift Normal file
View File

@@ -0,0 +1,128 @@
import Testing
@testable import TXCore
@Suite("会话生命周期状态机")
struct SessionMachineTests {
@Test("正常连接流程")
func happyPath() {
var m = SessionMachine()
#expect(m.reduce(.connectRequested) == [.startConnect])
#expect(m.phase == .connecting)
#expect(m.reduce(.authenticating) == [])
#expect(m.phase == .authenticating)
#expect(m.reduce(.established) == [.notify("已连接")])
#expect(m.phase == .connected)
}
@Test("认证失败为终态，不自动重连")
func authFailedTerminal() {
var m = SessionMachine()
_ = m.reduce(.connectRequested)
let effects = m.reduce(.authFailed(reason: "密码错误"))
#expect(m.phase == .failed(reason: "密码错误"))
#expect(effects.contains(.teardownTransport))
// failed 态收到网络事件不动
#expect(m.reduce(.transportClosed(reason: nil)) == [])
#expect(m.phase == .failed(reason: "密码错误"))
}
@Test("断线进入退避重连")
func disconnectSchedulesReconnect() {
var m = SessionMachine()
_ = m.reduce(.connectRequested)
_ = m.reduce(.established)
let effects = m.reduce(.transportClosed(reason: "eof"))
#expect(m.phase == .waitingToReconnect(attempt: 1))
#expect(effects.contains(.teardownTransport))
#expect(effects.contains(.scheduleReconnect(attempt: 1, delayMS: 500)))
}
@Test("重连计时→重连→成功")
func reconnectSuccess() {
var m = SessionMachine()
_ = m.reduce(.connectRequested)
_ = m.reduce(.established)
_ = m.reduce(.transportClosed(reason: nil))
#expect(m.reduce(.reconnectTimerFired) == [.startConnect])
#expect(m.phase == .reconnecting(attempt: 1))
#expect(m.reduce(.established) == [.notify("已重连")])
#expect(m.phase == .connected)
}
@Test("重连反复失败，退避递增，达上限转 failed")
func reconnectExhaustion() {
var m = SessionMachine(maxReconnectAttempts: 3, baseDelayMS: 500, maxDelayMS: 16000)
_ = m.reduce(.connectRequested)
_ = m.reduce(.established)
// 第1次断
_ = m.reduce(.transportClosed(reason: nil))
#expect(m.phase == .waitingToReconnect(attempt: 1))
_ = m.reduce(.reconnectTimerFired) // reconnecting(1)
// 第2次断（attempt 2, delay 1000）
let e2 = m.reduce(.transportClosed(reason: nil))
#expect(m.phase == .waitingToReconnect(attempt: 2))
#expect(e2.contains(.scheduleReconnect(attempt: 2, delayMS: 1000)))
_ = m.reduce(.reconnectTimerFired) // reconnecting(2)
// 第3次断（attempt 3, delay 2000）
let e3 = m.reduce(.transportClosed(reason: nil))
#expect(m.phase == .waitingToReconnect(attempt: 3))
#expect(e3.contains(.scheduleReconnect(attempt: 3, delayMS: 2000)))
_ = m.reduce(.reconnectTimerFired) // reconnecting(3)
// 第4次断 → 超过 maxReconnectAttempts(3) → failed
let e4 = m.reduce(.transportClosed(reason: "gone"))
if case .failed = m.phase {} else { Issue.record("期望 failed，实际 \(m.phase)") }
#expect(e4.contains(.notify("重连失败，请手动重试")))
}
@Test("退避封顶")
func backoffCap() {
let m = SessionMachine(baseDelayMS: 500, maxDelayMS: 16000)
#expect(m.backoffDelayMS(attempt: 1) == 500)
#expect(m.backoffDelayMS(attempt: 2) == 1000)
#expect(m.backoffDelayMS(attempt: 5) == 8000)
#expect(m.backoffDelayMS(attempt: 6) == 16000)
#expect(m.backoffDelayMS(attempt: 10) == 16000) // 封顶
}
@Test("后台冻结与前台恢复")
func backgroundResume() {
var m = SessionMachine()
_ = m.reduce(.connectRequested)
_ = m.reduce(.established)
#expect(m.reduce(.enteredBackground) == [])
#expect(m.phase == .backgroundParked)
let effects = m.reduce(.enteredForeground)
#expect(m.phase == .reconnecting(attempt: 1))
#expect(effects.contains(.startConnect))
}
@Test("等待重连时进入后台取消计时")
func backgroundDuringWait() {
var m = SessionMachine()
_ = m.reduce(.connectRequested)
_ = m.reduce(.established)
_ = m.reduce(.transportClosed(reason: nil))
#expect(m.phase == .waitingToReconnect(attempt: 1))
#expect(m.reduce(.enteredBackground) == [.cancelReconnectTimer])
#expect(m.phase == .backgroundParked)
}
@Test("主动关闭与手动重试复位")
func closeAndRetry() {
var m = SessionMachine()
_ = m.reduce(.connectRequested)
_ = m.reduce(.established)
let closeEffects = m.reduce(.closeRequested)
#expect(m.phase == .closed)
#expect(closeEffects.contains(.teardownTransport))
// failed 后手动重试
var m2 = SessionMachine()
_ = m2.reduce(.connectRequested)
_ = m2.reduce(.authFailed(reason: "x"))
#expect(m2.reduce(.retryRequested) == [.startConnect])
#expect(m2.phase == .connecting)
}
}

118
packages/TXCore/Tests/TXCoreTests/TmuxControlParserTests.swift Normal file
View File

@@ -0,0 +1,118 @@
import Testing
import Foundation
@testable import TXCore
@Suite("tmux control-mode 解析器")
struct TmuxControlParserTests {
@Test("命令应答块按序号关联")
func commandBlock() {
let p = TmuxControlParser()
let events = p.feed("%begin 1678 7 1\nhello\nworld\n%end 1678 7 1\n")
#expect(events.count == 1)
guard case .commandResponse(let r) = events[0] else {
Issue.record("期望 commandResponse"); return
}
#expect(r.number == 7)
#expect(r.isError == false)
#expect(r.lines == ["hello", "world"])
}
@Test("%error 块标记为错误")
func errorBlock() {
let p = TmuxControlParser()
let events = p.feed("%begin 1 3 1\nno server\n%error 1 3 1\n")
guard case .commandResponse(let r) = events.first else {
Issue.record("期望 commandResponse"); return
}
#expect(r.isError)
#expect(r.number == 3)
}
@Test("块内以 % 开头的行不解释为通知")
func percentInsideBlock() {
let p = TmuxControlParser()
let events = p.feed("%begin 1 1 1\n%output not-a-notification\n%end 1 1 1\n")
#expect(events.count == 1)
guard case .commandResponse(let r) = events.first else {
Issue.record("期望 commandResponse"); return
}
#expect(r.lines == ["%output not-a-notification"])
}
@Test("%output 解析出 pane 与字节")
func output() {
let p = TmuxControlParser()
let events = p.feed("%output %2 ready\\012\n")
guard case .output(let pane, let data) = events.first else {
Issue.record("期望 output"); return
}
#expect(pane == TmuxPaneID(2))
#expect(data == Data("ready\n".utf8))
}
@Test("跨 feed 的残行被正确缓冲")
func splitAcrossFeeds() {
let p = TmuxControlParser()
#expect(p.feed("%output %0 par").isEmpty) // 无换行 → 无事件
let events = p.feed("tial\n")
guard case .output(_, let data) = events.first else {
Issue.record("期望 output"); return
}
#expect(data == Data("partial".utf8))
}
@Test("CRLF 行尾被容忍")
func crlf() {
let p = TmuxControlParser()
let events = p.feed("%window-add @5\r\n")
#expect(events == [.windowAdd(TmuxWindowID(5))])
}
@Test("窗口生命周期通知")
func windowNotifications() {
let p = TmuxControlParser()
#expect(p.feed("%window-add @1\n") == [.windowAdd(TmuxWindowID(1))])
#expect(p.feed("%window-close @1\n") == [.windowClose(TmuxWindowID(1))])
#expect(p.feed("%window-renamed @2 my shell\n")
== [.windowRenamed(TmuxWindowID(2), name: "my shell")])
}
@Test("会话与布局通知")
func sessionAndLayout() {
let p = TmuxControlParser()
#expect(p.feed("%session-changed $1 main\n")
== [.sessionChanged(TmuxSessionID(1), name: "main")])
let layout = p.feed("%layout-change @3 bc62,80x24,0,0,0\n")
#expect(layout == [.layoutChange(window: TmuxWindowID(3),
layout: "bc62,80x24,0,0,0",
visibleLayout: nil)])
}
@Test("流控与退出")
func flowControlAndExit() {
let p = TmuxControlParser()
#expect(p.feed("%pause %4\n") == [.pause(TmuxPaneID(4))])
#expect(p.feed("%continue %4\n") == [.unpause(TmuxPaneID(4))])
#expect(p.feed("%exit\n") == [.exit(reason: nil)])
#expect(p.feed("%exit server exited\n") == [.exit(reason: "server exited")])
}
@Test("未知通知降级为 .unknown 而非崩溃")
func unknownNotification() {
let p = TmuxControlParser()
let events = p.feed("%some-future-notification foo bar\n")
#expect(events == [.unknown(line: "%some-future-notification foo bar")])
}
@Test("attach 后的隐式空块")
func implicitEmptyBlock() {
let p = TmuxControlParser()
let events = p.feed("%begin 100 0 0\n%end 100 0 0\n")
guard case .commandResponse(let r) = events.first else {
Issue.record("期望空 commandResponse"); return
}
#expect(r.lines.isEmpty)
#expect(r.number == 0)
}
}

29
packages/TXCore/Tests/TXCoreTests/TmuxControlSequenceTests.swift Normal file
View File

@@ -0,0 +1,29 @@
import Testing
@testable import TXCore
@Suite("tmux -CC 哨兵序列检测")
struct TmuxControlSequenceTests {
@Test("查找进入 DCS")
func findEnter() {
let stream = Array("shell output\r\n".utf8) + TmuxControlSequence.enter + Array("%begin".utf8)
let idx = TmuxControlSequence.find(TmuxControlSequence.enter, in: stream)
#expect(idx == Array("shell output\r\n".utf8).count)
}
@Test("查找退出 ST")
func findExit() {
let stream = Array("%exit\n".utf8) + TmuxControlSequence.exit
#expect(TmuxControlSequence.find(TmuxControlSequence.exit, in: stream) == Array("%exit\n".utf8).count)
}
@Test("未出现返回 nil")
func notFound() {
#expect(TmuxControlSequence.find(TmuxControlSequence.enter, in: Array("normal text".utf8)) == nil)
}
@Test("enter 序列即 ESC P 1000 p")
func enterBytes() {
#expect(TmuxControlSequence.enter == [0x1B, 0x50, 0x31, 0x30, 0x30, 0x30, 0x70])
}
}

59
packages/TXCore/Tests/TXCoreTests/TmuxLayoutTests.swift Normal file
View File

@@ -0,0 +1,59 @@
import Testing
@testable import TXCore
@Suite("tmux layout 字符串解析")
struct TmuxLayoutTests {
@Test("单 pane")
func single() throws {
let l = try TmuxLayout.parse("bc62,80x24,0,0,0")
#expect(l.root == .leaf(pane: TmuxPaneID(0),
rect: .init(width: 80, height: 24, x: 0, y: 0)))
#expect(l.paneIDs == [TmuxPaneID(0)])
}
@Test("左右分屏 {} → horizontal")
func horizontalSplit() throws {
let l = try TmuxLayout.parse("a1b2,80x24,0,0{40x24,0,0,1,39x24,41,0,2}")
guard case .horizontal(let children, let rect) = l.root else {
Issue.record("期望 horizontal"); return
}
#expect(rect == .init(width: 80, height: 24, x: 0, y: 0))
#expect(children.count == 2)
#expect(children[0] == .leaf(pane: TmuxPaneID(1), rect: .init(width: 40, height: 24, x: 0, y: 0)))
#expect(children[1] == .leaf(pane: TmuxPaneID(2), rect: .init(width: 39, height: 24, x: 41, y: 0)))
#expect(l.paneIDs == [TmuxPaneID(1), TmuxPaneID(2)])
}
@Test("上下分屏 [] → vertical")
func verticalSplit() throws {
let l = try TmuxLayout.parse("ffff,80x24,0,0[80x12,0,0,1,80x11,0,13,2]")
guard case .vertical(let children, _) = l.root else {
Issue.record("期望 vertical"); return
}
#expect(children.count == 2)
#expect(l.paneIDs == [TmuxPaneID(1), TmuxPaneID(2)])
}
@Test("嵌套：左右分屏，右侧再上下分屏")
func nested() throws {
let l = try TmuxLayout.parse("0000,100x40,0,0{50x40,0,0,1,49x40,51,0[49x20,51,0,2,49x19,51,21,3]}")
guard case .horizontal(let top, _) = l.root else {
Issue.record("期望 horizontal"); return
}
#expect(top.count == 2)
#expect(top[0] == .leaf(pane: TmuxPaneID(1), rect: .init(width: 50, height: 40, x: 0, y: 0)))
guard case .vertical(let inner, _) = top[1] else {
Issue.record("期望嵌套 vertical"); return
}
#expect(inner.count == 2)
#expect(l.paneIDs == [TmuxPaneID(1), TmuxPaneID(2), TmuxPaneID(3)])
}
@Test("畸形字符串抛错而非崩溃")
func malformed() {
#expect(throws: TmuxLayout.ParseError.self) { try TmuxLayout.parse("garbage") }
#expect(throws: TmuxLayout.ParseError.self) { try TmuxLayout.parse("abcd,80x24,0,0{") }
#expect(throws: TmuxLayout.ParseError.self) { try TmuxLayout.parse("abcd,80x,0,0,0") }
}
}

51
packages/TXCore/Tests/TXCoreTests/TmuxOutputDecoderTests.swift Normal file
View File

@@ -0,0 +1,51 @@
import Testing
import Foundation
@testable import TXCore
@Suite("tmux %output 八进制解码")
struct TmuxOutputDecoderTests {
// 通过公开 API 间接验证 decode（decoder 为 internal）。
private func decode(_ escaped: String) -> Data {
let parser = TmuxControlParser()
let events = parser.feed("%output %0 \(escaped)\n")
guard case .output(_, let data) = events.first else {
Issue.record("期望 .output，得到 \(events)")
return Data()
}
return data
}
@Test("普通字符原样通过")
func plain() {
#expect(decode("hello") == Data("hello".utf8))
}
@Test("空格不转义，原样保留")
func rawSpace() {
#expect(decode("hello\\040world") == Data("hello world".utf8))
// payload 中的真实空格也应保留
#expect(decode("a b") == Data("a b".utf8))
}
@Test("控制字符八进制还原")
func controlBytes() {
#expect(decode("line\\015\\012") == Data([0x6C, 0x69, 0x6E, 0x65, 0x0D, 0x0A]))
}
@Test("反斜杠自身 \\134")
func backslash() {
#expect(decode("a\\134b") == Data([0x61, 0x5C, 0x62]))
}
@Test("不完整转义序列原样保留")
func malformedEscape() {
// 末尾孤立反斜杠 + 不足三位
#expect(decode("x\\12") == Data("x\\12".utf8))
}
@Test("非八进制数字（8/9）不视为转义")
func nonOctalDigits() {
#expect(decode("\\189") == Data("\\189".utf8))
}
}