Wish SSH 代码审查指南

速查表

审查关卡（Review gates）

撰写书面审查报告时，请**严格按顺序执行以下步骤**。在当前步骤的通过条件（Pass when）未对被审查代码全部满足前，**不得在后续步骤中提出缺陷**。

1. 定位 Wish 入口点 — 通过条件：为每个服务暴露面（server surface），至少找出一条仓库路径，该路径中调用了 wish.NewServer、wish.WithMiddleware，注册了 bubbletea.Middleware，或定义了顶层 ssh.Handler 链（请明确列出所有路径）。
2. 采集服务器初始化证据 — 通过条件：对步骤 1 中的每条路径，均需提供实际使用的 wish.WithHostKey* / 主机密钥配置，以及**源码中声明的完整中间件列表（按源码顺序）**（不可凭记忆复述）。若实现了优雅关闭（graceful shutdown），请注明 ListenAndServe 和 Shutdown 的调用所在文件。
3. 采集会话 / TUI 相关证据 — 通过条件：对每个 teaHandler（或等效实现），需从源码中确认：是否在使用窗口尺寸前调用了 s.Pty()；当应用 Lipgloss 样式时，是否为每个会话单独创建了渲染器（即是否使用 bubbletea.MakeRenderer）。
4. 撰写审查发现 — 通过条件：每项发现须采用 [FILE:LINE] ISSUE_TITLE 格式（必要时可标注行范围），并明确指向 速查表 中对应条目（或 references/ 下匹配的章节）。

审查检查清单

本清单需与 审查关卡 配合使用；撰写书面审查报告时，请先完成全部关卡，确保下方每一项均可关联到已引用的具体源码位置。

• 主机密钥（host keys）从文件加载或安全生成
• 中间件顺序正确（日志记录置于首位，认证逻辑尽早执行）
• 使用会话上下文（session context）维护连接级状态
• 优雅关闭机制能妥善处理活跃会话
• 正确处理 PTY 请求，以支持终端类应用
• 连接数限制机制可防止资源耗尽
• 超时中间件可防止连接长期挂起
• BubbleTea 中间件配置正确

关键模式

服务器初始化

// GOOD - 完整的服务器初始化
s, err := wish.NewServer(
    wish.WithAddress(fmt.Sprintf("%s:%d", host, port)),
    wish.WithHostKeyPath(".ssh/id_ed25519"),
    wish.WithMiddleware(
        logging.Middleware(),       // 首位：记录所有连接
        activeterm.Middleware(),    // 处理终端尺寸变更
        bubbletea.Middleware(teaHandler),
    ),
)
if err != nil {
    return fmt.Errorf("creating server: %w", err)
}

优雅关闭（Graceful Shutdown）

// BAD - 突然终止
log.Fatal(s.ListenAndServe())

// GOOD - 优雅关闭
done := make(chan os.Signal, 1)
signal.Notify(done, os.Interrupt, syscall.SIGTERM)

go func() {
    if err := s.ListenAndServe(); err != nil && !errors.Is(err, ssh.ErrServerClosed) {
        log.Error("server error", "error", err)
    }
}()

<-done
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
if err := s.Shutdown(ctx); err != nil {
    log.Error("shutdown error", "error", err)
}

BubbleTea Handler

func teaHandler(s ssh.Session) (tea.Model, []tea.ProgramOption) {
    pty, _, _ := s.Pty()

    model := NewModel(pty.Window.Width, pty.Window.Height)

    return model, []tea.ProgramOption{
        tea.WithAltScreen(),
        tea.WithMouseCellMotion(),
    }
}

何时查阅参考文档

• 审查服务器初始化逻辑 → 查阅 server.md
• 审查认证流程、会话状态管理 → 查阅 sessions.md

审查问题清单

1. 主机密钥是否得到安全处理？
2. 中间件顺序是否正确？
3. 是否实现了优雅关闭？
4. PTY 窗口尺寸是否正确传递至 TUI？
5. 是否配置了连接超时？