diff --git a/server/go/cmd/main.go b/server/go/cmd/main.go index 1f218dc..32ad615 100644 --- a/server/go/cmd/main.go +++ b/server/go/cmd/main.go @@ -131,8 +131,11 @@ func (h *MyHandler) OnReceive(ctx *connection.Context, data []byte) { h.handleTerminalStart(ctx, false) case protocol.TokenTerminalClose: // Pre-bind close (rare — device gives up before the server - // finished its half of the handshake). Best-effort cleanup. - if devID := h.deviceIDOfSubConn(ctx); devID != "" { + // finished its half of the handshake). Best-effort cleanup, but only + // of a pending lease: an unbound sub-conn carries no lease identity, + // and after a re-login it may be a stale orphan whose close would + // otherwise tear down a shell someone else has since opened. + if devID := h.deviceIDOfSubConn(ctx); devID != "" && h.hub.IsTerminalPending(devID) { h.log.Info("pre-bind terminal close: device=%s conn=%d", devID, ctx.ID) h.hub.CloseTerminalSession(devID) } diff --git a/server/go/hub/hub.go b/server/go/hub/hub.go index c035112..76c45fa 100644 --- a/server/go/hub/hub.go +++ b/server/go/hub/hub.go @@ -94,9 +94,13 @@ type Device struct { // and after teardown. // terminalIsPTY: distinguishes Linux/macOS/ConPTY (true) from the legacy // Windows cmd-pipe path. PTY mode supports resize; cmd-pipe ignores it. + // terminalGen: identifies one lease. Every successful open bumps it, so a + // viewer that lost the lease (a re-login drops a pending request, then + // someone else opens) cannot close the new owner's shell. terminalPending bool terminalConn *connection.Context terminalIsPTY bool + terminalGen uint64 } // ScreenCache is a read-only snapshot of a device's last-seen screen state, @@ -496,6 +500,7 @@ func (h *Hub) Register(d *Device, conn *connection.Context) { d.cursorSeen, d.lastCursorIndex = prev.cursorSeen, prev.lastCursorIndex d.lastCursorX, d.lastCursorY, d.cursorPubAt = prev.lastCursorX, prev.lastCursorY, prev.cursorPubAt d.terminalConn, d.terminalIsPTY = prev.terminalConn, prev.terminalIsPTY + d.terminalGen = prev.terminalGen } h.devices[d.ID] = d info := deviceToInfo(d) @@ -754,37 +759,57 @@ var ErrTerminalBusy = errors.New("terminal already open by another viewer") // returns ErrTerminalBusy. Mirrors C++ CWebService::HandleTermOpen // (server/2015Remote/WebService.cpp:1838). func (h *Hub) OpenTerminalSession(deviceID string) error { + _, err := h.openTerminalSession(deviceID) + return err +} + +// OpenTerminalSessionLease is OpenTerminalSession that also returns the lease +// generation. A caller that later closes via CloseTerminalSessionLease can +// only tear down the lease it opened: if the session was dropped (device +// re-login) and taken over by another viewer, the generation no longer matches +// and the close is a no-op. +func (h *Hub) OpenTerminalSessionLease(deviceID string) (uint64, error) { + return h.openTerminalSession(deviceID) +} + +func (h *Hub) openTerminalSession(deviceID string) (uint64, error) { if deviceID == "" { - return ErrDeviceOffline + return 0, ErrDeviceOffline } h.mu.Lock() d, ok := h.devices[deviceID] if !ok || d.conn == nil { h.mu.Unlock() - return ErrDeviceOffline + return 0, ErrDeviceOffline } if d.terminalPending || d.terminalConn != nil { h.mu.Unlock() - return ErrTerminalBusy + return 0, ErrTerminalBusy } d.terminalPending = true + // The generation is bumped with the pending flag, under the same lock: a + // later open can only start once this lease is gone, and it bumps again, so + // an older generation can never match a newer owner's lease. + d.terminalGen++ + gen := d.terminalGen mainConn := d.conn h.mu.Unlock() if h.sender == nil { - // Roll back so a retry isn't permanently blocked. + // Roll back so a retry isn't permanently blocked. The generation stays + // bumped; it is only an identity, not a resource. h.mu.Lock() d.terminalPending = false h.mu.Unlock() - return ErrNoSender + return 0, ErrNoSender } if err := h.sender(mainConn, []byte{protocol.CommandShell}); err != nil { h.mu.Lock() d.terminalPending = false h.mu.Unlock() - return err + return 0, err } - return nil + return gen, nil } // IsTerminalPending tells the TCP layer whether the next-arriving shell @@ -919,20 +944,29 @@ func (h *Hub) TerminalIsPTY(id string) bool { // send COMMAND_BYE, then close after a short grace period so the client's // IOCPClient reconnect logic doesn't fire. func (h *Hub) CloseTerminalSession(deviceID string) { - h.closeTerminalPinned(deviceID, nil) + h.closeTerminalPinned(deviceID, nil, 0) +} + +// CloseTerminalSessionLease tears down the session only if its lease +// generation still matches gen. False means the lease was already gone (or was +// renewed by another open) and nothing was touched. +func (h *Hub) CloseTerminalSessionLease(deviceID string, gen uint64) bool { + return h.closeTerminalPinned(deviceID, nil, gen) } // CloseTerminalSessionPinned is CloseTerminalSession restricted to a device // still pinned to main; see CloseScreenPinned for why the disconnect path // needs the ownership check. func (h *Hub) CloseTerminalSessionPinned(deviceID string, main *connection.Context) bool { - return h.closeTerminalPinned(deviceID, main) + return h.closeTerminalPinned(deviceID, main, 0) } -func (h *Hub) closeTerminalPinned(deviceID string, main *connection.Context) bool { +// closeTerminalPinned tears down the session. gen==0 closes whatever lease the +// device holds; a non-zero gen closes only that lease. +func (h *Hub) closeTerminalPinned(deviceID string, main *connection.Context, gen uint64) bool { h.mu.Lock() d, ok := h.devices[deviceID] - if !ok || (main != nil && d.conn != main) { + if !ok || (main != nil && d.conn != main) || (gen != 0 && d.terminalGen != gen) { h.mu.Unlock() return false } diff --git a/server/go/hub/register_session_test.go b/server/go/hub/register_session_test.go index b612960..bb53ec3 100644 --- a/server/go/hub/register_session_test.go +++ b/server/go/hub/register_session_test.go @@ -188,3 +188,38 @@ func TestRegisterDoesNotCarryPendingTerminal(t *testing.T) { t.Fatalf("retry after re-register: %v, want nil", err) } } + +// A lease generation is an ownership proof: a stale opener whose pending +// request a re-login dropped cannot close the lease someone else acquired +// afterwards, while the current owner can still close its own. +func TestCloseTerminalSessionLeaseIgnoresRenewedLease(t *testing.T) { + h := New() + h.SetSender(func(ctx *connection.Context, data []byte) error { return nil }) + h.Register(&Device{ID: "dev", PeerIP: "10.0.0.1"}, + &connection.Context{RemoteAddr: "10.0.0.1:1000"}) + + stale, err := h.OpenTerminalSessionLease("dev") + if err != nil { + t.Fatalf("first open: %v", err) + } + // Re-login drops the pending request without an OnTerminalClosed event. + h.Register(&Device{ID: "dev", PeerIP: "10.0.0.1"}, + &connection.Context{RemoteAddr: "10.0.0.1:1002"}) + + current, err := h.OpenTerminalSessionLease("dev") + if err != nil { + t.Fatalf("second open: %v", err) + } + if h.CloseTerminalSessionLease("dev", stale) { + t.Fatal("a stale generation closed the renewed lease") + } + if !h.HasTerminalSession("dev") { + t.Fatal("renewed lease was torn down by the stale close") + } + if !h.CloseTerminalSessionLease("dev", current) { + t.Fatal("the owning generation could not close its lease") + } + if h.HasTerminalSession("dev") { + t.Fatal("lease still held after the owner closed it") + } +} diff --git a/server/go/mcp/server.go b/server/go/mcp/server.go index 83caad1..b5049c2 100644 --- a/server/go/mcp/server.go +++ b/server/go/mcp/server.go @@ -10,6 +10,7 @@ import ( "net/http" "runtime/debug" "strings" + "sync" "time" "github.com/yuanyuanxiang/SimpleRemoter/server/go/devicehistory" @@ -29,6 +30,10 @@ const ( defaultTermIdle = 180 * time.Second defaultMaxConcurrency = 16 defaultReadMax = 2 << 20 + + // termSweepInterval is how often the reaper looks for sessions a model + // forgot to close. The sweep itself is cheap: one mutex per session. + termSweepInterval = 30 * time.Second ) // Config is filled by cmd/main.go from the YAMA_MCP_* environment variables; @@ -71,6 +76,13 @@ type Server struct { locks *deviceLocks sem chan struct{} sessions *sessionTable + + // stop ends the idle reaper and reaperDone reports that it returned; + // closeOnce makes Close idempotent (tests call it both explicitly and from + // Cleanup). reaperDone is nil when no reaper was started (hub-less server). + stop chan struct{} + reaperDone chan struct{} + closeOnce sync.Once } // New builds the endpoint. Zero-valued knobs fall back to the documented @@ -102,6 +114,7 @@ func New(cfg Config) *Server { handlers: make(map[string]toolFunc), locks: newDeviceLocks(), sem: make(chan struct{}, cfg.MaxConcurrency), + stop: make(chan struct{}), } if cfg.Hub != nil { s.sessions = newSessionTable(cfg.Hub) @@ -110,6 +123,12 @@ func New(cfg Config) *Server { } s.registerLocalTools() s.registerTerminalTools() + if cfg.Hub != nil { + // No hub means no shell can ever be opened, so there is nothing to + // reap; skipping the goroutine keeps hub-less servers inert. + s.reaperDone = make(chan struct{}) + go s.sweepLoop() + } return s } @@ -118,9 +137,34 @@ func New(cfg Config) *Server { // unknown path. func (s *Server) Enabled() bool { return s != nil && s.cfg.Token != "" } -// Close releases resources held by long-lived tool state: every terminal -// session MCP owns is torn down and the shell told to exit. -func (s *Server) Close() { s.sessions.closeAll() } +// Close releases resources held by long-lived tool state: the reaper stops and +// every terminal session MCP owns is torn down and the shell told to exit. +func (s *Server) Close() { + s.closeOnce.Do(func() { + close(s.stop) + if s.reaperDone != nil { + <-s.reaperDone + } + s.sessions.closeAll() + }) +} + +// sweepLoop reclaims terminal sessions nobody closed. The interval shrinks to +// TermIdle when that is shorter, so a test (or a deliberately tiny idle knob) +// sees the sweep fire on schedule instead of up to 30 s late. +func (s *Server) sweepLoop() { + defer close(s.reaperDone) + ticker := time.NewTicker(min(termSweepInterval, s.cfg.TermIdle)) + defer ticker.Stop() + for { + select { + case <-s.stop: + return + case now := <-ticker.C: + s.sessions.sweepIdle(now, s.cfg.TermIdle) + } + } +} // Handle serves POST /mcp. Transport-level failures (405/401/413) are answered // here; everything after a successfully parsed JSON-RPC request returns HTTP @@ -303,7 +347,7 @@ func (s *Server) callTool(ctx context.Context, raw json.RawMessage) (result any, s.cfg.MaxConcurrency) } - if deviceID != "" { + if deviceID != "" && !unlockedTools[params.Name] { held, acquired := s.locks.tryAcquire(deviceID, params.Name) if !acquired { return nil, errf(CodeBusy, "%s", busyMessage(held)) diff --git a/server/go/mcp/session.go b/server/go/mcp/session.go index 6acc6d8..c4e4992 100644 --- a/server/go/mcp/session.go +++ b/server/go/mcp/session.go @@ -22,8 +22,8 @@ var errNoDeviceHub = errors.New("no device hub configured") // keeps the table testable and documents that MCP never touches a terminal // sub-connection directly — it goes through the hub's single-viewer lease. type terminalHub interface { - OpenTerminalSession(deviceID string) error - CloseTerminalSession(deviceID string) + OpenTerminalSessionLease(deviceID string) (uint64, error) + CloseTerminalSessionLease(deviceID string, lease uint64) bool HasTerminalSession(deviceID string) bool SendToTerminal(deviceID string, data []byte) error } @@ -72,7 +72,8 @@ func (t *sessionTable) open(deviceID string) (*termSession, error) { t.byDevice[deviceID] = sess t.mu.Unlock() - if err := t.hub.OpenTerminalSession(deviceID); err != nil { + lease, err := t.hub.OpenTerminalSessionLease(deviceID) + if err != nil { t.mu.Lock() delete(t.byDevice, deviceID) t.mu.Unlock() @@ -87,6 +88,7 @@ func (t *sessionTable) open(deviceID string) (*termSession, error) { sess.mu.Lock() sess.opening = false + sess.lease = lease sess.mu.Unlock() // An explicit close (or shutdown) may have removed the entry while the hub @@ -96,7 +98,7 @@ func (t *sessionTable) open(deviceID string) (*termSession, error) { cur, ok := t.byDevice[deviceID] t.mu.Unlock() if !ok || cur != sess { - t.hub.CloseTerminalSession(deviceID) + t.hub.CloseTerminalSessionLease(deviceID, lease) return nil, errSessionClosed } return sess, nil @@ -192,63 +194,120 @@ func (t *sessionTable) closeSession(deviceID string) bool { // exactly want. The identity check matters for sweepIdle: between its scan // and the close, the stale session can be replaced by a fresh one. func (t *sessionTable) closeSessionIf(deviceID string, want *termSession) bool { + return t.closeIf(deviceID, want, func(*termSession) string { return "closed" }) +} + +// closeIf closes a session if decide says so. decide runs with both locks held +// (table then session), so it must read only session fields and lock nothing: +// the staleness reaper uses it to re-check under the same lock that deletes, +// closing the scan-then-close window where a poll could refresh the session. +// A returned "" cancels the close and nothing is touched. +func (t *sessionTable) closeIf(deviceID string, want *termSession, decide func(*termSession) string) bool { t.mu.Lock() sess, ok := t.byDevice[deviceID] if !ok || (want != nil && sess != want) { t.mu.Unlock() return false } - delete(t.byDevice, deviceID) - t.mu.Unlock() sess.mu.Lock() + reason := decide(sess) + if reason == "" { + sess.mu.Unlock() + t.mu.Unlock() + return false + } + delete(t.byDevice, deviceID) wasClosed := sess.closed + lease := sess.lease sess.closed = true - sess.closeReason = "closed" + sess.closeReason = reason sess.cond.Broadcast() sess.mu.Unlock() + t.mu.Unlock() // A session that was already closed lost its hub lease when the close event // arrived; the hub may since have handed a fresh shell to another viewer (a - // reconnected device). Only an explicit close of a live session may touch it. - if t.hub != nil && !wasClosed { - // Fires OnTerminalClosed, which is a no-op now that the entry is gone. - t.hub.CloseTerminalSession(deviceID) + // reconnected device). Only an explicit close of a live session may touch + // it, and even then only the lease MCP itself opened (the generation check + // in the hub), never whatever lease the device holds now. + if t.hub != nil && !wasClosed && lease != 0 { + t.hub.CloseTerminalSessionLease(deviceID, lease) } return true } -// sweepIdle closes sessions whose last use is older than idle. Intended for -// the periodic reaper: a model that forgets terminal_close must not lock a -// human out of the device's shell. +// termBusyMax bounds how long one command may hold a session with nobody +// polling it. Without it a hung command — or a model that never comes back — +// would lock the device's single terminal slot forever. MFC reclaims at the +// same one-hour limit (McpServer.cpp:4674). +const termBusyMax = time.Hour + +// sweepIdle closes sessions whose last use is older than idle, plus live +// commands that outlived termBusyMax. Intended for the periodic reaper: a +// model that forgets terminal_close must not lock a human out of the device's +// shell. // -// The M4c reaper must skip sessions with an in-flight command (pending != -// nil): a quiet command (sleep, a slow download) still owns the lease and -// must not be reaped just because it printed nothing for a while. +// A session with a live command (pending, not done) is skipped no matter how +// quiet it is: a sleep or a slow download still owns the lease and must not be +// reaped just because it printed nothing for a while. A session whose shell is +// already gone is reaped on idle alone — its only remaining value is the +// undelivered tail, and a model that never polls it must not pin the slot. +// A session that never became ready is left alone: its open is still waiting +// on a caller, which releases it (with a lease-checked close) on its own. func (t *sessionTable) sweepIdle(now time.Time, idle time.Duration) int { - type staleEntry struct { + type entry struct { id string sess *termSession } - var stale []staleEntry + var candidates []entry t.mu.Lock() for id, sess := range t.byDevice { - sess.mu.Lock() - last := sess.lastUsed - sess.mu.Unlock() - if now.Sub(last) >= idle { - stale = append(stale, staleEntry{id, sess}) - } + candidates = append(candidates, entry{id, sess}) } t.mu.Unlock() n := 0 - for _, e := range stale { - if t.closeSessionIf(e.id, e.sess) { + for _, e := range candidates { + if t.closeIf(e.id, e.sess, func(s *termSession) string { + return s.reclaimReasonLocked(now, idle) + }) { n++ } } return n } +// reclaimReasonLocked returns why the session should be dropped, or "" to keep +// it. Callers hold s.mu. +func (s *termSession) reclaimReasonLocked(now time.Time, idle time.Duration) string { + inactive := func() string { + return fmt.Sprintf( + "Terminal session was reclaimed after %s of inactivity; call terminal_exec again to open a new one", idle) + } + if !s.ready { + // Still waiting for the shell to bind; a caller holds this session and + // releases it when its own wait ends. Reaping here would kill a live + // open (and, if the lease changed hands meanwhile, someone else's). + return "" + } + if s.closed { + if now.Sub(s.lastUsed) >= idle { + return inactive() + } + return "" + } + if p := s.pending; p != nil && !p.done { + if now.Sub(p.busySince) >= termBusyMax { + return fmt.Sprintf( + "Terminal session was reclaimed after the command ran longer than %s; call terminal_exec again to open a new one", termBusyMax) + } + return "" + } + if now.Sub(s.lastUsed) >= idle { + return inactive() + } + return "" +} + // closeAll drops every session; used at shutdown. The hub teardown is still // best-effort because the TCP servers may already be stopping. func (t *sessionTable) closeAll() { diff --git a/server/go/mcp/session_test.go b/server/go/mcp/session_test.go index 83be532..c25438d 100644 --- a/server/go/mcp/session_test.go +++ b/server/go/mcp/session_test.go @@ -239,6 +239,7 @@ func TestSessionIdleSweep(t *testing.T) { t.Fatalf("open: %v", err) } sess.mu.Lock() + sess.ready = true sess.lastUsed = time.Now().Add(-time.Hour) sess.mu.Unlock() @@ -408,3 +409,137 @@ func TestSentinelSplitAcrossChunks(t *testing.T) { t.Fatalf("split sentinel: done=%v code=%d", done, code) } } + +// A quiet command still owns the device's shell lease: the reaper must not +// reclaim a session just because it printed nothing for a while. +func TestSweepKeepsRunningCommand(t *testing.T) { + tbl := newSessionTable(nil) + sess := newTermSession("1001") + sess.ready = true + sess.lastUsed = sess.lastUsed.Add(-time.Hour) + sess.pending = &pendingCmd{start: 0, busySince: time.Now()} + tbl.byDevice["1001"] = sess + + if n := tbl.sweepIdle(time.Now(), time.Minute); n != 0 { + t.Fatalf("swept = %d, want 0 while the command runs", n) + } + if tbl.get("1001") != sess { + t.Fatal("running session was removed") + } +} + +// Once the shell is gone, only the undelivered tail keeps the session alive; +// a model that never polls must not pin the slot indefinitely. +func TestSweepReapsClosedDrainingSession(t *testing.T) { + tbl := newSessionTable(nil) + sess := newTermSession("1001") + sess.ready = true + sess.closed = true + sess.pending = &pendingCmd{busySince: time.Now()} + sess.lastUsed = sess.lastUsed.Add(-time.Hour) + tbl.byDevice["1001"] = sess + + if n := tbl.sweepIdle(time.Now(), time.Minute); n != 1 { + t.Fatalf("swept = %d, want 1", n) + } + if tbl.get("1001") != nil { + t.Fatal("draining session not removed") + } +} + +// The reaper is wired to a ticker in New: an idle session is reclaimed without +// any further tool call. +func TestSweepTickerReclaimsIdleSession(t *testing.T) { + h := hub.New() + h.SetSender(func(*connection.Context, []byte) error { return nil }) + h.Register(&hub.Device{ID: "1001", PeerIP: "10.0.0.1"}, + &connection.Context{RemoteAddr: "10.0.0.1:54321"}) + s := New(Config{Token: testToken, Hub: h, TermIdle: 100 * time.Millisecond}) + t.Cleanup(s.Close) + + if _, err := s.sessions.open("1001"); err != nil { + t.Fatalf("open: %v", err) + } + s.OnTerminalReady("1001", true) + + deadline := time.Now().Add(3 * time.Second) + for s.sessions.get("1001") != nil { + if time.Now().After(deadline) { + t.Fatal("idle session was not reaped by the ticker") + } + time.Sleep(10 * time.Millisecond) + } + if h.HasTerminalSession("1001") { + t.Fatal("reaped session still holds the hub lease") + } +} + +// A command that outlives the busy cap is reclaimed even with no output and no +// poller, so a hung shell cannot hold the device slot forever. +func TestSweepReapsOverdueCommand(t *testing.T) { + tbl := newSessionTable(nil) + sess := newTermSession("1001") + sess.ready = true + sess.lastUsed = sess.lastUsed.Add(-time.Minute) + sess.pending = &pendingCmd{start: 0, busySince: time.Now().Add(-termBusyMax - time.Second)} + tbl.byDevice["1001"] = sess + + if n := tbl.sweepIdle(time.Now(), time.Minute); n != 1 { + t.Fatalf("swept = %d, want 1 for an overdue command", n) + } + if tbl.get("1001") != nil { + t.Fatal("overdue session not removed") + } +} + +// A session whose shell never bound has a caller still waiting on it; the +// reaper must leave it to that caller's own release path. +func TestSweepKeepsNotReadySession(t *testing.T) { + tbl := newSessionTable(nil) + sess := newTermSession("1001") + sess.lastUsed = sess.lastUsed.Add(-time.Hour) + tbl.byDevice["1001"] = sess + + if n := tbl.sweepIdle(time.Now(), time.Minute); n != 0 { + t.Fatalf("swept = %d, want 0 for a session still opening", n) + } + if tbl.get("1001") != sess { + t.Fatal("not-ready session was removed") + } +} + +// A device re-login drops a pending lease without emitting OnTerminalClosed. +// If a human then takes the freed slot, a late close from the MCP session that +// lost it must not tear the human's shell down (design §6.2: never pre-empt). +func TestCloseLeavesRenewedLeaseAlone(t *testing.T) { + s, h := terminalTestServer(t) + sess, err := s.sessions.open("1001") + if err != nil { + t.Fatalf("open: %v", err) + } + // Register carries the terminal generation over, exactly like a real + // re-login racing the old connection's disconnect. + h.Register(&hub.Device{ID: "1001", PeerIP: "10.0.0.1"}, + &connection.Context{RemoteAddr: "10.0.0.1:54321"}) + if err := h.OpenTerminalSession("1001"); err != nil { + t.Fatalf("human open: %v", err) + } + + if !s.sessions.closeSessionIf("1001", sess) { + t.Fatal("close did not remove the stale session") + } + if !h.HasTerminalSession("1001") { + t.Fatal("close tore down a lease the stale session no longer owned") + } +} + +func TestCloseStopsReaper(t *testing.T) { + s, _ := terminalTestServer(t) + s.Close() + select { + case <-s.reaperDone: + default: + t.Fatal("Close returned before the reaper stopped") + } + s.Close() // idempotent; the Cleanup will call it a third time +} diff --git a/server/go/mcp/term.go b/server/go/mcp/term.go index da429dc..16ad21b 100644 --- a/server/go/mcp/term.go +++ b/server/go/mcp/term.go @@ -55,9 +55,10 @@ type termSession struct { droppedBytes uint64 isPTY bool - ready bool // OnTerminalReady seen - sawOutput bool // shell printed its first screen (prompt); bootstrap done - opening bool // hub.OpenTerminalSession still in flight + ready bool // OnTerminalReady seen + sawOutput bool // shell printed its first screen (prompt); bootstrap done + opening bool // hub.OpenTerminalSession still in flight + lease uint64 // hub lease generation; 0 until the open completes closed bool closeReason string diff --git a/server/go/mcp/tools.go b/server/go/mcp/tools.go index 652b2bb..6f80018 100644 --- a/server/go/mcp/tools.go +++ b/server/go/mcp/tools.go @@ -20,6 +20,14 @@ var writeTools = map[string]bool{ "terminal_close": true, } +// unlockedTools run without the per-device lock. terminal_close must be usable +// while a terminal_exec call is still waiting on the same device: that call +// holds the lock for its whole timeout, and a close that answers -32003 could +// never interrupt it. +var unlockedTools = map[string]bool{ + "terminal_close": true, +} + // toolDef holds one published definition plus its name, so filtering does not // re-parse the JSON on every tools/list call. type toolDef struct { diff --git a/server/go/mcp/tools_term.go b/server/go/mcp/tools_term.go index 92e9037..0bebe55 100644 --- a/server/go/mcp/tools_term.go +++ b/server/go/mcp/tools_term.go @@ -54,8 +54,60 @@ type terminalExecOutput struct { ElapsedMS int64 `json:"elapsed_ms"` } +// terminalCloseArgs is the published inputSchema as Go. +type terminalCloseArgs struct { + ID string `json:"id"` + SessionID string `json:"session_id"` +} + +type terminalCloseOutput struct { + Closed bool `json:"closed"` +} + func (s *Server) registerTerminalTools() { s.handlers["terminal_exec"] = s.callTerminalExec + s.handlers["terminal_close"] = s.callTerminalClose +} + +// callTerminalClose releases the persistent session MCP opened for a device. +// +// It is idempotent for the session it is given: a session that is already gone +// still answers closed, so a retried close after a timeout does not fail. Only +// sessions in MCP's own table are touched — the web console's shell is left +// alone, and the hub-side close is lease-checked, so a session whose lease was +// taken over is never torn down. +// +// A session_id that names a different live session is a caller mistake +// (-32002), mirroring the Win32 server (McpServer.cpp BuildTerminalClose). +func (s *Server) callTerminalClose(_ context.Context, raw json.RawMessage) (any, *rpcError) { + if s.cfg.Hub == nil { + return nil, errf(CodeInternal, "server device registry is not configured") + } + var args terminalCloseArgs + if rerr := decodeArgs(raw, &args); rerr != nil { + return nil, rerr + } + if args.ID == "" { + return nil, errf(CodeInvalidParams, "Missing required parameter: id") + } + if !isDecimalID(args.ID) { + return nil, errf(CodeInvalidParams, "Invalid id: expected a decimal host id string") + } + if args.SessionID == "" { + return nil, errf(CodeInvalidParams, "Missing required parameter: session_id") + } + if sess := s.sessions.get(args.ID); sess != nil { + if sess.id != args.SessionID { + return nil, errf(CodeOffline, "Terminal session_id mismatch: %s", args.SessionID) + } + // Wakes any terminal_exec still waiting on the command; it delivers the + // bytes buffered so far (done=true, exit_code=-1) before it returns. + s.sessions.closeSessionIf(args.ID, sess) + } + return toolResult{ + Content: []contentItem{{Type: "text", Text: "closed"}}, + StructuredContent: terminalCloseOutput{Closed: true}, + }, nil } // callTerminalExec runs one command or polls the output of the previous one. diff --git a/server/go/mcp/tools_term_test.go b/server/go/mcp/tools_term_test.go index b7e3f4b..d0760ce 100644 --- a/server/go/mcp/tools_term_test.go +++ b/server/go/mcp/tools_term_test.go @@ -69,12 +69,16 @@ func newTermRig(t *testing.T, clientType, capability string, isPTY bool) *termRi t.Cleanup(unsub) t.Cleanup(rig.s.Close) - // The device answers COMMAND_SHELL by opening a shell sub-connection. + // The device answers COMMAND_SHELL by opening a shell sub-connection. The + // loop keeps answering, so a test can close a session and reopen at once. go func() { - select { - case <-rig.opened: - h.BindTerminalConn("1001", sub, isPTY) - case <-rig.stop: + for { + select { + case <-rig.opened: + h.BindTerminalConn("1001", sub, isPTY) + case <-rig.stop: + return + } } }() return rig @@ -149,6 +153,41 @@ func (r *termRig) feed(text string) { r.s.OnTerminalData("1001", termPacket(text)) } +// callClose runs terminal_close directly on the handler, bypassing the HTTP +// layer's device lock (which the handler must ignore anyway). +func (r *termRig) callClose(args string) (terminalCloseOutput, *rpcError) { + r.t.Helper() + res, rerr := r.s.callTerminalClose(context.Background(), json.RawMessage(args)) + if rerr != nil { + return terminalCloseOutput{}, rerr + } + tr, ok := res.(toolResult) + if !ok { + r.t.Fatalf("unexpected close result type %T", res) + } + if len(tr.Content) != 1 || tr.Content[0].Text != "closed" { + r.t.Fatalf("close content = %+v", tr.Content) + } + out, ok := tr.StructuredContent.(terminalCloseOutput) + if !ok { + r.t.Fatalf("unexpected close structured content %T", tr.StructuredContent) + } + return out, nil +} + +// runToCompletion runs one command through the rig to its sentinel. +func (r *termRig) runToCompletion(command, output string) termCall { + r.t.Helper() + ch := r.callAsync(fmt.Sprintf(`{"id":"1001","command":%q,"timeout_ms":5000}`, command)) + _, nonce := r.nextCommandWire() + r.feed("@" + "echo off & " + command + "\r\n" + output + "\r\n__MCP_DONE_" + nonce + "__0\r\n") + res := r.wait(ch) + if res.err != nil || !res.out.Done { + r.t.Fatalf("runToCompletion(%q) = %+v / %v", command, res.out, res.err) + } + return res +} + func TestTerminalExecRunsCommand(t *testing.T) { rig := newTermRig(t, "", "", true) ch := rig.callAsync(`{"id":"1001","command":"echo hello","timeout_ms":5000}`) @@ -557,3 +596,174 @@ func TestTerminalExecBootstrapHonoursCallTimeout(t *testing.T) { t.Fatalf("bootstrap ignored the call timeout: %v", elapsed) } } + +// terminal_close releases the MCP-owned session and is idempotent: a second +// close (or a close after a reap) still answers closed instead of an error. +func TestTerminalCloseIsIdempotent(t *testing.T) { + rig := newTermRig(t, "", "", true) + sid := rig.runToCompletion("echo hello", "hello").out.SessionID + + out, rerr := rig.callClose(fmt.Sprintf(`{"id":"1001","session_id":%q}`, sid)) + if rerr != nil || !out.Closed { + t.Fatalf("close = %+v / %v", out, rerr) + } + if rig.s.sessions.get("1001") != nil { + t.Fatal("closed session still in the table") + } + if rig.h.HasTerminalSession("1001") { + t.Fatal("closed session still holds the hub lease") + } + + out, rerr = rig.callClose(fmt.Sprintf(`{"id":"1001","session_id":%q}`, sid)) + if rerr != nil || !out.Closed { + t.Fatalf("second close = %+v / %v", out, rerr) + } +} + +func TestTerminalCloseRejectsMismatchedSession(t *testing.T) { + rig := newTermRig(t, "", "", true) + rig.runToCompletion("echo hello", "hello") + + _, rerr := rig.callClose(`{"id":"1001","session_id":"s-000000"}`) + if rerr == nil || rerr.Code != CodeOffline || !strings.Contains(rerr.Message, "mismatch") { + t.Fatalf("mismatched close = %+v", rerr) + } + if rig.s.sessions.get("1001") == nil { + t.Fatal("mismatched close removed the session") + } +} + +func TestTerminalCloseRejectsBadArgs(t *testing.T) { + rig := newTermRig(t, "", "", true) + for _, args := range []string{ + `{"session_id":"s-abcdef"}`, // missing id + `{"id":"abc","session_id":"s-abcdef"}`, // id not decimal + `{"id":"1001"}`, // missing session_id + } { + if _, rerr := rig.callClose(args); rerr == nil || rerr.Code != CodeInvalidParams { + t.Fatalf("%s: %+v", args, rerr) + } + } +} + +// A terminal_close that lands while terminal_exec is waiting must wake that +// call: it delivers the bytes buffered so far and reports the shell gone. +func TestTerminalCloseInterruptsRunningCommand(t *testing.T) { + rig := newTermRig(t, "", "", true) + ch := rig.callAsync(`{"id":"1001","command":"ping -n 30 127.0.0.1","timeout_ms":5000}`) + _, _ = rig.nextCommandWire() + rig.feed("partial output\r\n") + + sess := rig.s.sessions.get("1001") + if sess == nil { + t.Fatal("session missing while the command runs") + } + if out, rerr := rig.callClose(fmt.Sprintf(`{"id":"1001","session_id":%q}`, sess.id)); rerr != nil || !out.Closed { + t.Fatalf("close = %+v / %v", out, rerr) + } + + res := rig.wait(ch) + if res.err != nil { + t.Fatalf("exec after close: %v", res.err) + } + if res.out.Stdout != "partial output" || !res.out.Done { + t.Fatalf("exec after close = %+v, want the buffered tail", res.out) + } + if res.out.ExitCode == nil || *res.out.ExitCode != -1 { + t.Fatalf("exit code = %+v, want -1", res.out.ExitCode) + } + if rig.s.sessions.get("1001") != nil { + t.Fatal("closed session still in the table") + } +} + +// With no waiter, close discards the tail but still releases the device slot: +// the next poll reports the session gone rather than serving stale bytes. +func TestTerminalCloseWithoutWaiterReleasesSlot(t *testing.T) { + rig := newTermRig(t, "", "", true) + ch := rig.callAsync(`{"id":"1001","command":"ping -n 30 127.0.0.1","timeout_ms":100}`) + _, _ = rig.nextCommandWire() + first := rig.wait(ch) + if first.err != nil || first.out.Done { + t.Fatalf("first call = %+v / %v", first.out, first.err) + } + sid := first.out.SessionID + rig.feed("orphan\r\n") + + if out, rerr := rig.callClose(fmt.Sprintf(`{"id":"1001","session_id":%q}`, sid)); rerr != nil || !out.Closed { + t.Fatalf("close = %+v / %v", out, rerr) + } + if rig.s.sessions.get("1001") != nil { + t.Fatal("closed session still in the table") + } + if rig.h.HasTerminalSession("1001") { + t.Fatal("closed session still holds the hub lease") + } + + ch = rig.callAsync(fmt.Sprintf(`{"id":"1001","session_id":%q,"timeout_ms":100}`, sid)) + res := rig.wait(ch) + if res.err == nil || res.err.Code != CodeOffline || !strings.Contains(res.err.Message, "not found") { + t.Fatalf("poll after close = %+v", res.err) + } +} + +// A closed session must not keep the device slot: the very next command opens +// a fresh shell immediately. +func TestTerminalCloseAllowsImmediateReopen(t *testing.T) { + rig := newTermRig(t, "", "", true) + sid := rig.runToCompletion("echo one", "one").out.SessionID + if _, rerr := rig.callClose(fmt.Sprintf(`{"id":"1001","session_id":%q}`, sid)); rerr != nil { + t.Fatalf("close: %v", rerr) + } + + start := time.Now() + res := rig.runToCompletion("echo two", "two") + if elapsed := time.Since(start); elapsed > time.Second { + t.Fatalf("reopen took %v, want under 1s", elapsed) + } + if res.out.SessionID == sid { + t.Fatalf("reopen reused the closed session id %q", sid) + } + if res.out.Stdout != "two" { + t.Fatalf("reopen output = %q", res.out.Stdout) + } +} + +// terminal_close only knows MCP's own table: a shell the web console holds has +// no MCP session, so the call is a no-op for the hub lease. +func TestTerminalCloseLeavesBrowserSessionAlone(t *testing.T) { + rig := newTermRig(t, "", "", true) + if err := rig.h.OpenTerminalSession("1001"); err != nil { + t.Fatalf("browser open: %v", err) + } + if out, rerr := rig.callClose(`{"id":"1001","session_id":"s-abcdef"}`); rerr != nil || !out.Closed { + t.Fatalf("close = %+v / %v", out, rerr) + } + if !rig.h.HasTerminalSession("1001") { + t.Fatal("terminal_close released a browser-held lease") + } +} + +// The HTTP layer must not make terminal_close wait on the per-device lock: +// an in-flight terminal_exec holds it for the whole call timeout. +func TestTerminalCloseIgnoresDeviceLock(t *testing.T) { + rig := newTermRig(t, "", "", true) + rig.runToCompletion("echo hello", "hello") // the session stays open after a finished command + + sess := rig.s.sessions.get("1001") + if sess == nil { + t.Fatal("session missing") + } + if _, ok := rig.s.locks.tryAcquire("1001", "terminal_exec"); !ok { + t.Fatal("could not take the device lock") + } + defer rig.s.locks.release("1001") + + if _, rerr := rig.s.callTool(context.Background(), json.RawMessage( + fmt.Sprintf(`{"name":"terminal_close","arguments":{"id":"1001","session_id":%q}}`, sess.id))); rerr != nil { + t.Fatalf("close through tools/call: %v", rerr) + } + if rig.s.sessions.get("1001") != nil { + t.Fatal("close through tools/call did not release the session") + } +}