Feature(Go): terminal_close, idle sweep and legacy-client guard

Add the terminal_close tool so a caller can release a shell session
explicitly instead of waiting for it to age out. The tool is idempotent
for the session it names, rejects a session_id that does not match the
live session with -32002, and runs without the per-device lock so it can
interrupt a terminal_exec call that is still polling on the same device.

Give hub leases a generation counter: the generation is bumped when a
pending lease is created and carried across a device re-login. MCP-side
closes pass the generation, so a stale session can no longer tear down a
shell a human operator opened after the device reconnected. The reaper
runs on a 30 s ticker (shortened when TermIdle is smaller), skips
sessions that are still opening, and reclaims idle sessions as well as
commands overdue past the one-hour busy cap.

The pre-bind terminal-close path in cmd no longer closes
unconditionally; it touches only a pending lease, because an unbound
sub-connection carries no lease identity and may be a stale orphan.

Covered by unit tests for close semantics, lock exemption, reaper
lifecycle and lease-generation ownership, plus a live run against a
Debug ghost: close before and during a command, reopen, idle reap and
mismatched-id rejection all behave as specified.

Co-Authored-By: deepseek-flash
This commit is contained in:
yuanyuanxianganddeepseek-flash committed 2026-11-12 21:53:54 +01:00
1 parent 599c891c00
commit 808747f9d2
10 files changed
+633 -52

No files matched your search

+5 -2
View File
@@ -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)
}
+45 -11
View File
@@ -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
}
+35
View File
@@ -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")
}
}
+48 -4
View File
@@ -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))
+86 -27
View File
@@ -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() {
+135
View File
@@ -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
}
+4 -3
View File
@@ -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
+8
View File
@@ -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 {
+52
View File
@@ -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.
+215 -5
View File
@@ -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")
}
}