Files
Piik/internal/app/console.go
T
AAA 9150e9d312 feat(app): improve startup, diagnostics and direct connections (#397)
## Problem and outcome / 问题与结果

Machines with several local addresses could fail before opening Piik, and startup or connection failures were difficult to diagnose. This phase adds Local invitation-address selection and accessible diagnostics, preserves useful startup errors, and repairs media preparation and recovery without changing room authority or routing policy. It also aligns language handling, playback, public downloads and contributor documentation with the resulting behavior.

## Release notes

### 中文

- **多网卡也能正常选择启动方式。** 本地房间在需要时显示网卡名称与局域网地址,供你选择朋友所在的网络;公网邀请和连接已有站点不再因多个局域网地址而无法启动。
- **更容易排查启动和连接问题。** 启动页新增“诊断启动”,同时记录 App 与网页诊断;网页版也有独立诊断入口。启动失败会显示具体原因和重试方法,Windows 双击启动后的错误会停留等待确认。诊断模式下异常退出会保存报告,ZIP 由用户自行保留或清理。
- **减少连接准备中的无谓等待。** 普通候选发现不再等待可选端口映射;修正连接重启时旧候选与完成通知的处理,以及部分准备失败后的反馈。Native 媒体连接可在网络支持时使用 IPv6 直连,同时保留 IPv4 路径。
- **修正分享恢复中的状态问题。** 切换画面后重新计算首播保护所需的新帧;SFU 恢复时应用最新画质设置;一次应答发送失败不再使整个会话失去 Native 接收能力。密码错误提示也进行了去重。
- **改善播放与全屏交互。** 同步 Safari 原生全屏中的播放、音量与退出状态;可操作的视频画面显示手形光标。
- **统一语言匹配并完善翻译贡献。** 简体、繁体中文系统均默认显示简体中文,其余系统默认英文;保留中英文与纯视觉模式快捷切换,提供中英文社区翻译教程和额外语言接入方式。
- **整理下载与官网说明。** Release 附件集中展示三个平台的 App ZIP 和 Server 程序包,源码版本与校验值收进更新说明的折叠区。官网保留内嵌短片,并提供独立观看链接;教程、下载文案和运维指南同步更新。

**升级:** App 请完整解压对应平台的 ZIP 并保留目录结构。服务端按部署指南升级,保留现有配置与 SQLite 数据。此次更新不改变现有通信协议和存储格式。

**测试范围:** 主要验证 Windows App 与桌面浏览器。macOS、Linux 实机采集和移动端、跨公网 IPv6 的更广泛验证仍待完成,欢迎试用反馈。

### English

- **Choose how to start on machines with multiple network addresses.** Local rooms show interface names and invitation addresses when a choice is needed. Public invitations and connections to an existing Site no longer fail because several LAN addresses are available.
- **Diagnose startup and connection problems more easily.** The launcher now offers Debug launch for both App and browser diagnostics, alongside a separate browser diagnostics control. Startup failures include their cause and retry guidance; Windows errors remain visible for confirmation after a double-click launch. Failed exits in diagnostic mode save a report. Exported ZIPs remain available until you move or delete them.
- **Remove unnecessary connection setup waits.** Ordinary candidate discovery no longer waits for optional gateway mapping. Fixes cover stale candidates and completion signals during ICE restarts, and feedback from failed connection preparation. Native media can use direct IPv6 connections where available while retaining IPv4 paths.
- **Keep sharing recovery aligned with the current source and settings.** Source changes count new frames for startup protection, SFU recovery uses the latest quality preferences, and one failed answer submission no longer disables Native receiving for the entire session. Duplicate password-error feedback has also been removed.
- **Improve playback and fullscreen interaction.** Safari native fullscreen now synchronizes playback, volume and exit state. Interactive video surfaces show a pointer cursor.
- **Align language selection and community translation guidance.** Simplified and Traditional Chinese system locales select Simplified Chinese; other systems default to English. Chinese, English and visual-mode shortcuts remain, with bilingual translation guides and a registration path for additional languages.
- **Simplify release downloads and refresh the website.** Release attachments contain the three App ZIPs and the Server runtime archive; source identity and checksums appear in a collapsed section of the release notes. The website keeps its embedded introduction and adds a standalone viewing link, with updated setup, download and operations guidance.

**Upgrading:** Extract the complete App ZIP for your platform and keep its directory structure. Follow the deployment guide for Server upgrades, preserving existing configuration and SQLite data. Existing wire contracts and storage formats are unchanged.

**Test coverage:** Windows App and desktop browsers are the primary validated paths. Physical macOS/Linux capture, broader mobile coverage and IPv6 across separate public networks remain open; testing and feedback are welcome.

## Verification / 验证

- `npm run check`: PASS, including TypeScript, 807 tests in 60 files and the production Web build.
- `npm run check:client`: PASS on Windows, including Go formatting/tests/vet, Windows/Linux core builds and native Windows capture compile/probe. Darwin requires the native macOS CI runner.
- `npm run gate:client-media`: PASS with Chrome 152 and a real captured test window on Windows. Two receivers obtained video and audio; live and paused profile changes, recovery frames and cleanup passed. This is a single-machine test, not a public-NAT success-rate measurement.
- `npm run gate:client-link`: PASS using the newly packaged Windows App. A separate remote machine fetched its temporary public page and completed the WebSocket upgrade; App exit closed the link and cleanup passed.
- Server runtime and Windows App candidate packaging: PASS, including archive identity/checksums and execution from the extracted App ZIP. Native Linux/macOS package checks still run in the publishing pipeline before publication.
- `node scripts/check-docs.mjs`, `scripts/check-project-state.ps1`, `git diff --check` and `npm run build:website`: PASS. Seven documentation-size gardening advisories and the existing Vite chunk-size advisory remain non-blocking.
- Browser review: English/Chinese website setup and direct-download links, narrow layout and diagnostics/language controls checked. Native popover accessibility correctly exposes expanded/collapsed state without a duplicate attribute owner.
- Independent audit found no P0/P1/P2 issues; focused race checks for portmapping and mediaedge passed. Diagnostic archive accumulation is retained by the owner's explicit choice. The currently unreachable language menu placement issue is a first-community-language prerequisite in TODO.

Physical macOS/Linux capture, broader mobile behavior, restricted-network/endurance coverage and cross-network Native IPv6 remain explicitly outside this candidate's evidence.

## Impact / 影响

Compatible feature release, planned as v1.2.0 from v1.1.2. Browser/server v23, Native control v9, capture v7 and SQLite schema 2 remain unchanged. No new telemetry service, retry policy or configuration requirement is introduced. Public Demo remains open-entry and P2P-only. NAT-PMP dependency corrections are explicitly deferred to the next release and are not claimed here.

The existing product, configuration, translation, research and operations owners were updated. Raw audits, handoffs, diagnostic logs and experimental sources are excluded from the PR.
2026-09-13 18:32:24 +08:00

571 lines
16 KiB
Go

package app
import (
"context"
"fmt"
"io"
"math/rand/v2"
"net/url"
"os"
"path/filepath"
"strings"
"sync"
"time"
tea "charm.land/bubbletea/v2"
"charm.land/lipgloss/v2"
"github.com/TNTcraftHIM/Piik/internal/app/browser"
"github.com/charmbracelet/colorprofile"
"github.com/charmbracelet/x/ansi"
"github.com/charmbracelet/x/term"
)
type consoleView struct {
mode, state, entry, invite string
protected bool
problem string
}
type consoleLanguage string
type consoleFinished struct{ err error }
type consoleTick struct{}
type consoleIdleWink struct{}
type consoleOpenResult struct{ err error }
type consoleDiagnostic string
type consoleDebug struct {
logPath string
export func() (string, error)
}
type consoleExportResult struct {
path string
err error
}
type consoleModel struct {
view consoleView
language string
width int
height int
colors bool
frame int
tickPending bool
idlePending bool
idleWink bool
finished bool
cancel context.CancelFunc
debug consoleDebug
exporting bool
exportPath string
exportError bool
}
type console struct {
mu sync.Mutex
machine bool
finished bool
program *tea.Program
done chan error
plain consoleModel
}
var consoleCopy = map[string][3]string{
"mode": {"Mode", "模式", ""},
"local": {"Local network", "局域网", "□"},
"link": {"Public link", "公网链接", "↗"},
"site": {"Piik Site", "Piik 站点", "@"},
"setup": {"Choose a mode in the browser", "在浏览器中选择模式", "?"},
"starting": {"Starting", "正在启动", "…"},
"ready": {"Ready", "已就绪", "✓"},
"stopping": {"Stopping", "正在退出", "→"},
"stopped": {"Stopped", "已停止", "○"},
"failed": {"Could not continue", "运行失败", "!"},
"entry": {"Open in browser", "打开网页", "□"},
"invite": {"Site address", "站点地址", "↗"},
"access": {"Site access", "站点准入", ""},
"open": {"Open", "开放", "○"},
"password": {"Password protected", "已设置密码", "*"},
"error": {"Details", "详情", "!"},
"exit": {"quit", "退出", "↪"},
"openFailed": {"Could not open the browser; use the address above.", "无法打开浏览器,请使用上方地址。", "! ↗"},
"log": {"Log", "日志", ""},
"export": {"Export diagnostics", "导出诊断", ""},
"exporting": {"Saving diagnostics", "正在保存诊断", ""},
"exported": {"Saved", "已保存", ""},
"exportFailed": {"Could not save diagnostics", "无法保存诊断", ""},
}
func newConsole(cancel context.CancelFunc, machine bool) *console {
console := &console{
machine: machine,
plain: consoleModel{view: consoleView{state: "starting"}, language: defaultConsoleLanguage(), width: 76, cancel: cancel,
colors: colorprofile.Detect(os.Stdout, os.Environ()) > colorprofile.ASCII},
}
if machine {
return console
}
if term.IsTerminal(os.Stdin.Fd()) && term.IsTerminal(os.Stdout.Fd()) && os.Getenv("TERM") != "dumb" {
console.program = tea.NewProgram(console.plain, tea.WithoutSignalHandler())
console.done = make(chan error, 1)
go func() {
_, err := console.program.Run()
console.done <- err
cancel()
}()
}
return console
}
func (console *console) send(message tea.Msg) {
console.mu.Lock()
defer console.mu.Unlock()
if console.machine || console.finished {
return
}
if _, finished := message.(consoleFinished); finished {
console.finished = true
}
if console.program != nil {
console.program.Send(message)
return
}
updated, _ := console.plain.Update(message)
console.plain = updated.(consoleModel)
fmt.Fprintln(os.Stdout, console.plain.content(false))
}
func (console *console) show(view consoleView) { console.send(view) }
func (console *console) setLanguage(language string) { console.send(consoleLanguage(language)) }
func (console *console) finish(err error) error {
console.send(consoleFinished{err})
if console.program != nil {
terminalErr := <-console.done
if err != nil {
fmt.Fprintln(os.Stderr, "Piik App:", err)
}
if terminalErr != nil {
fmt.Fprintln(os.Stderr, "Piik App:", terminalErr)
}
return terminalErr
}
return nil
}
func (console *console) logWriter() io.Writer {
if console.program == nil {
return os.Stderr
}
return console
}
func (console *console) Write(data []byte) (int, error) {
if text := strings.TrimSpace(string(data)); text != "" {
console.send(consoleDiagnostic(ansi.Strip(text)))
}
return len(data), nil
}
func (model consoleModel) Init() tea.Cmd { return nil }
func (model consoleModel) Update(message tea.Msg) (tea.Model, tea.Cmd) {
switch value := message.(type) {
case consoleView:
if model.view.state != "stopping" {
model.view = value
}
case consoleLanguage:
model.language = string(value)
case consoleDiagnostic:
model.view.problem = string(value)
case consoleDebug:
model.debug = value
case consoleExportResult:
model.exporting, model.exportError = false, value.err != nil
if value.err == nil {
model.exportPath = value.path
}
case tea.WindowSizeMsg:
model.width, model.height = value.Width, value.Height
case tea.ColorProfileMsg:
model.colors = value.Profile > colorprofile.ASCII
case consoleTick:
model.tickPending = false
model.frame++
if model.frame >= 16 {
model.idleWink = false
}
case consoleIdleWink:
model.idlePending = false
if model.view.state == "ready" || model.view.state == "setup" {
model.frame, model.idleWink = 8, true
}
case consoleOpenResult:
if value.err != nil {
model.view.problem = model.text("openFailed")
}
case consoleFinished:
model.finished = true
model.view.entry, model.view.invite = "", ""
model.view.state, model.view.problem = "stopped", ""
if value.err != nil {
model.view.state, model.view.problem = "failed", value.err.Error()
}
return model, tea.Quit
case tea.KeyPressMsg:
switch value.String() {
case "q", "ctrl+c":
model.view = consoleView{mode: model.view.mode, state: "stopping"}
model.cancel()
case "o":
if target := model.view.entry; target != "" {
return model, func() tea.Msg { return consoleOpenResult{browser.Open(launchURL(consoleAddress(target)))} }
}
case "d", "D":
if model.debug.export != nil && !model.exporting && !model.finished && model.view.state != "stopping" {
model.exporting, model.exportError = true, false
return model, func() tea.Msg {
path, err := model.debug.export()
return consoleExportResult{path: path, err: err}
}
}
}
}
if model.animating() && !model.tickPending {
model.tickPending = true
return model, tea.Tick(200*time.Millisecond, func(time.Time) tea.Msg { return consoleTick{} })
}
if !model.finished && !model.animating() && !model.idlePending &&
(model.view.state == "ready" || model.view.state == "setup") {
model.idlePending = true
return model, tea.Tick(time.Duration(8+rand.IntN(13))*time.Second, func(time.Time) tea.Msg { return consoleIdleWink{} })
}
return model, nil
}
func (model consoleModel) animating() bool {
return !model.finished && model.view.state != "stopping" &&
(model.view.state == "starting" || model.frame < 8 || model.idleWink)
}
func (model consoleModel) text(key string) string {
index := 0
if model.language == "zh" {
index = 1
}
if model.language == "vis" {
return consoleVisualToken(key)
}
return consoleCopy[key][index]
}
func (model consoleModel) View() tea.View {
view := tea.NewView(model.content(true))
view.WindowTitle = "Piik App"
view.AltScreen = true
return view
}
func (model consoleModel) content(styled bool) string {
width := max(12, min(model.width-2, 74))
compact := model.height > 0 && model.height < 24
compactDebug := compact && model.debug.logPath != ""
visual := model.language == "vis"
accent, muted, link := lipgloss.NewStyle(), lipgloss.NewStyle(), lipgloss.NewStyle()
if styled {
accent = accent.Bold(true)
muted = muted.Faint(true)
link = link.Underline(true)
}
revision := BuildRevision
if len(revision) == 40 {
revision = revision[:7]
}
var out strings.Builder
version := buildVersion()
heading := "Piik\nApp\n" + muted.Render(version)
if revision != "" && revision != version {
heading = "Piik App\n" + muted.Render(version) + "\n" + muted.Render(revision)
}
animated := styled && model.animating()
mascot := accent.Render(consoleTV(model.frame, animated, compact || width < 34))
if styled && model.colors && width >= 36 && !compactDebug {
mascot = consoleBlockTV(model.frame, animated)
}
fmt.Fprintln(&out, lipgloss.JoinHorizontal(lipgloss.Center, mascot, heading))
fmt.Fprintln(&out)
state := model.text(model.view.state)
if model.view.state == "starting" && !visual {
dots := 3
if styled {
dots = model.frame%3 + 1
}
state += strings.Repeat(".", dots)
}
if visual {
stateStyle := accent
if styled && model.colors {
switch model.view.state {
case "ready":
stateStyle = stateStyle.Foreground(lipgloss.Color("#3fb97a"))
case "starting", "stopping":
stateStyle = stateStyle.Foreground(lipgloss.Color("#e8a33d"))
case "failed":
stateStyle = stateStyle.Foreground(lipgloss.Color("#e25a52"))
}
}
// Keep visual mode one line tall; multi-line scene art side by side
// collapses on narrow terminals and reads like missing characters.
fmt.Fprintln(&out, lipgloss.JoinHorizontal(lipgloss.Center,
accent.Render(consoleVisualToken(model.view.mode)), " · ",
stateStyle.Render(consoleVisualToken(model.view.state))))
} else if compactDebug && model.view.mode != "" {
fmt.Fprintf(&out, "%s %s\n", accent.Render(state), model.text(model.view.mode))
} else {
fmt.Fprintln(&out, accent.Render(state))
if model.view.mode != "" {
fmt.Fprintf(&out, "%s %s\n", muted.Render(model.text("mode")), model.text(model.view.mode))
}
}
for _, item := range [][2]string{{"entry", model.view.entry}, {"invite", model.view.invite}} {
if item[1] == "" || compact && item[0] == "invite" {
continue
}
address := consoleAddress(item[1])
style := link
if styled {
target := address
if item[0] == "entry" {
target = launchURL(address)
}
style = style.Hyperlink(target)
}
if compactDebug {
fmt.Fprintf(&out, "\n%s\n", style.Render(address))
} else if visual {
label := consoleVisualToken(item[0])
fmt.Fprintf(&out, "\n%s %s\n", label, style.Render(address))
} else {
fmt.Fprintf(&out, "\n%s\n%s\n", muted.Render(model.text(item[0])), style.Render(address))
}
}
accessPicture := ""
if !compact && model.view.entry != "" && (model.view.mode == "local" || model.view.mode == "link") {
access := "open"
if model.view.protected {
access = "password"
}
if visual {
accessPicture = consoleVisualToken(access) + " "
} else {
fmt.Fprintf(&out, "\n%s %s\n", muted.Render(model.text("access")), model.text(access))
}
}
if model.view.problem != "" {
lines := strings.Split(ansi.Hardwrap(ansi.Strip(model.view.problem), width-4, true), "\n")
if len(lines) > 3 {
lines = append(lines[:2], "...")
}
fmt.Fprintf(&out, "\n%s\n%s\n", model.text("error"), strings.Join(lines, "\n"))
}
if model.debug.logPath != "" {
path, label := model.debug.logPath, "log"
if model.exportPath != "" {
path, label = model.exportPath, "exported"
}
separator := "\n"
if compactDebug {
separator = " "
}
fmt.Fprintf(&out, "\n%s%s%s\n", muted.Render(model.text(label)), separator, consoleFileLink(path, path, link, styled))
if model.exporting {
fmt.Fprintln(&out, model.text("exporting"))
} else if model.exportError {
fmt.Fprintln(&out, model.text("exportFailed"))
}
}
if !model.finished {
keys := "[q / Ctrl+C]"
if !styled {
keys = "Ctrl+C"
}
help := keys + " " + model.text("exit")
if visual {
if model.view.entry != "" && styled {
help = "[o] ↗ " + help
}
help = lipgloss.JoinHorizontal(lipgloss.Center, accessPicture, help)
} else if model.view.entry != "" && styled {
separator := " "
if compact && model.debug.export != nil {
separator = "\n"
}
help = "[o] " + model.text("entry") + separator + help
}
if model.debug.export != nil && styled {
help = "[d] " + model.text("export") + "\n" + help
}
if visual {
fmt.Fprintf(&out, "\n%s", accent.Render(help))
} else {
fmt.Fprintf(&out, "\n%s", muted.Render(help))
}
}
content := ansi.Hardwrap(out.String(), width-4, true)
if !styled {
return content
}
padding := 1
if model.height > 0 && lipgloss.Height(content)+4 > model.height {
content = strings.ReplaceAll(content, "\n\n", "\n")
padding = 0
}
return lipgloss.NewStyle().Border(lipgloss.RoundedBorder()).
Padding(padding, 1).Width(width).Render(content)
}
func consoleVisualToken(key string) string {
switch key {
case "local":
return "□"
case "link":
return "↗"
case "site":
return "@"
case "setup":
return "?"
case "starting":
return "…"
case "ready":
return "✓"
case "stopping":
return "→"
case "stopped":
return "○"
case "failed", "error":
return "!"
case "open":
return "○"
case "password":
return "*"
case "entry":
return "□"
case "invite":
return "↗"
case "exit":
return "↪"
case "log":
return "LOG"
case "export":
return "ZIP"
case "exporting":
return "ZIP ..."
case "exported":
return "ZIP +"
case "exportFailed":
return "ZIP !"
default:
return "?"
}
}
func consoleTV(frame int, animated, compact bool) string {
phase := 0
if animated {
phase = frame % 8
}
eye := "o"
if !animated || phase >= 4 {
eye = "-"
}
if compact {
return " \\ / \n [o " + eye + "] \n / \\ "
}
stars := [3]string{" ", " ", " "}
if phase == 5 {
stars[2] = "*"
}
if phase == 6 {
stars[1] = "+"
}
if phase == 7 {
stars[0] = "."
}
lines := []string{
" \\ / " + stars[0] + " ",
" .----v----. " + stars[1] + " ",
" | o " + eye + " | " + stars[2] + " ",
" '---------' ",
" / \\ ",
}
return strings.Join(lines, "\n")
}
func consoleBlockTV(frame int, animated bool) string {
phase := 0
if animated {
phase = frame % 8
}
shell := lipgloss.NewStyle().Reverse(true)
spark := lipgloss.NewStyle().Foreground(lipgloss.Color("#f4c14d")).Faint(phase == 7)
// Digits reveal the shell clockwise before the face; subsequent loops keep it drawn.
rows := []string{" 2 2 ", " 2 2 ", " 0000011 ", "3sssssss1", "3sessses1", "3sssssss1", " 3222222 ", " 3 3 "}
lines := make([]string, 0, len(rows))
for rowIndex, row := range rows {
var line strings.Builder
for column, pixel := range row {
if animated && (pixel >= '0' && pixel <= '3' && frame < int(pixel-'0') || (pixel == 's' || pixel == 'e') && frame < 3) {
pixel = ' '
}
switch pixel {
case '0', '1', '2', '3':
line.WriteString(shell.Render(" "))
case 's':
line.WriteString(" ")
case 'e':
if column == len(row)-3 && (!animated || phase >= 4) {
line.WriteString("\u2584\u2584")
} else {
line.WriteString(shell.Render(" "))
}
default:
line.WriteString(" ")
}
}
star := " "
starStyle := spark
switch {
case phase == 5 && rowIndex == 4:
star = "\u2584\u2588\u2584"
case phase == 5 && rowIndex == 5:
star, starStyle = "\u2584 \u2584", spark.Reverse(true)
case phase == 6 && rowIndex == 2:
star = " \u2584 "
case phase == 7 && rowIndex == 1:
star = " ."
}
lines = append(lines, line.String()+starStyle.Render(star))
}
return strings.Join(lines, "\n")
}
func consoleAddress(raw string) string {
parsed, err := url.Parse(raw)
if err != nil {
return ""
}
parsed.User, parsed.RawQuery, parsed.Fragment, parsed.RawFragment, parsed.ForceQuery = nil, "", "", "", false
return parsed.String()
}
func consoleFileLink(path, label string, style lipgloss.Style, styled bool) string {
if !styled {
return label
}
path = filepath.ToSlash(path)
if !strings.HasPrefix(path, "/") {
path = "/" + path
}
address := url.URL{Scheme: "file", Path: path}
return style.Hyperlink(address.String()).Render(label)
}