Release idle showcase sessions automatically

server.py

@@ -34,6 +34,13 @@ MODELS_DIR = os.path.join(BASE_DIR, "models")
 
 MAX_CONCURRENT_RUNNERS = int(os.environ.get("MAX_CONCURRENT_RUNNERS", "3"))
 SESSION_TIMEOUT_SEC = int(os.environ.get("SESSION_TIMEOUT_SEC", "900"))  # 15 min
+IDLE_TIMEOUT_SEC = max(1, int(os.environ.get("IDLE_TIMEOUT_SEC", "720")))  # 12 min
+IDLE_WARNING_SEC = min(
+    IDLE_TIMEOUT_SEC, max(0, int(os.environ.get("IDLE_WARNING_SEC", "600")))
+)  # warn after 10 min idle
+HEARTBEAT_TIMEOUT_SEC = max(
+    30, int(os.environ.get("HEARTBEAT_TIMEOUT_SEC", "75"))
+)
 PROJECT_CACHE_TTL_SEC = float(os.environ.get("PROJECT_CACHE_TTL_SEC", "10"))
 RUNNER_CONNECT_TIMEOUT_SEC = float(os.environ.get("RUNNER_CONNECT_TIMEOUT_SEC", "8"))
 
@@ -60,6 +67,8 @@ _metrics = {
     "sessions_started": 0,
     "sessions_rejected": 0,
     "sessions_timed_out": 0,
+    "sessions_idle_timed_out": 0,
+    "sessions_heartbeat_timed_out": 0,
     "sessions_failed_connect": 0,
 }
 
@@ -67,6 +76,19 @@ _metrics = {
 _project_cache: dict[str, Any] = {"tree": None, "built_at": 0.0, "signature": None}
 
 
+def _session_idle_state(
+    idle_for_sec: float,
+    warning_sec: float = IDLE_WARNING_SEC,
+    timeout_sec: float = IDLE_TIMEOUT_SEC,
+) -> str:
+    """Return active, warning, or timeout for a session's idle duration."""
+    if idle_for_sec >= timeout_sec:
+        return "timeout"
+    if warning_sec < timeout_sec and idle_for_sec >= warning_sec:
+        return "warning"
+    return "active"
+
+
 # ---------------------------------------------------------------------------
 # Project scanning (cached)
 # ---------------------------------------------------------------------------
@@ -302,6 +324,9 @@ async def health():
         "active_sessions": len(active_sessions),
         "max_concurrent_runners": MAX_CONCURRENT_RUNNERS,
         "session_timeout_sec": SESSION_TIMEOUT_SEC,
+        "idle_warning_sec": IDLE_WARNING_SEC,
+        "idle_timeout_sec": IDLE_TIMEOUT_SEC,
+        "heartbeat_timeout_sec": HEARTBEAT_TIMEOUT_SEC,
     }
 
 
@@ -452,6 +477,9 @@ async def run_project_page(request: Request, student_token: str, project_name: s
             "appetize_key": appetize_key,
             "view_only": view_only,
             "session_timeout_sec": SESSION_TIMEOUT_SEC,
+            "idle_warning_sec": IDLE_WARNING_SEC,
+            "idle_timeout_sec": IDLE_TIMEOUT_SEC,
+            "heartbeat_interval_sec": min(20, max(10, HEARTBEAT_TIMEOUT_SEC // 3)),
             "max_concurrent_runners": MAX_CONCURRENT_RUNNERS,
         },
     )
@@ -564,6 +592,9 @@ async def play_project_ws_internal(
     await websocket.accept()
     session_id = f"{real_class}/{real_student}/{project_name}/{time.time():.0f}"
     started_at = time.time()
+    started_monotonic = time.monotonic()
+    last_activity_at = started_monotonic
+    last_client_seen_at = started_monotonic
 
     async with _sessions_lock:
         active_sessions[session_id] = {
@@ -571,6 +602,7 @@ async def play_project_ws_internal(
             "student": real_student,
             "project": project_name,
             "started_at": started_at,
+            "last_activity_at": started_at,
         }
         _metrics["sessions_started"] += 1
 
@@ -667,26 +699,41 @@ async def play_project_ws_internal(
                 log.exception("tcp_to_ws error: %s", e)
 
         async def ws_to_tcp():
+            nonlocal last_activity_at, last_client_seen_at
             try:
                 while True:
                     data = await websocket.receive()
+                    now = time.monotonic()
+                    last_client_seen_at = now
                     if "text" in data:
                         message = json.loads(data["text"])
                         mtype = message.get("type")
 
-                        if mtype in ("keydown", "keyup"):
+                        if mtype == "heartbeat":
+                            continue
+
+                        if mtype == "activity":
+                            last_activity_at = now
+                            active_sessions[session_id]["last_activity_at"] = time.time()
+                        elif mtype in ("keydown", "keyup"):
+                            last_activity_at = now
+                            active_sessions[session_id]["last_activity_at"] = time.time()
                             payload = json.dumps(message).encode("utf-8")
                             runner_writer.write(
                                 b"KEYS" + len(payload).to_bytes(4, "big") + payload
                             )
                             await runner_writer.drain()
                         elif mtype in ("mousemove", "mousedown", "mouseup"):
+                            last_activity_at = now
+                            active_sessions[session_id]["last_activity_at"] = time.time()
                             payload = json.dumps(message).encode("utf-8")
                             runner_writer.write(
                                 b"MOUS" + len(payload).to_bytes(4, "big") + payload
                             )
                             await runner_writer.drain()
                         elif mtype == "cv2key":
+                            last_activity_at = now
+                            active_sessions[session_id]["last_activity_at"] = time.time()
                             payload = json.dumps(
                                 {"key_code": message.get("keyCode")}
                             ).encode("utf-8")
@@ -695,6 +742,8 @@ async def play_project_ws_internal(
                             )
                             await runner_writer.drain()
                         elif mtype == "terminal_input":
+                            last_activity_at = now
+                            active_sessions[session_id]["last_activity_at"] = time.time()
                             text = message.get("data", "")
                             if not text.endswith("\n"):
                                 text += "\n"
@@ -704,6 +753,7 @@ async def play_project_ws_internal(
                             )
                             await runner_writer.drain()
                         elif mtype == "pygame_quit":
+                            last_activity_at = now
                             runner_writer.write(b"QUIT" + (0).to_bytes(4, "big") + b"")
                             await runner_writer.drain()
                     elif "bytes" in data:
@@ -718,34 +768,92 @@ async def play_project_ws_internal(
                 log.exception("ws_to_tcp error: %s", e)
 
         async def session_watchdog():
-            await asyncio.sleep(SESSION_TIMEOUT_SEC)
-            _metrics["sessions_timed_out"] += 1
-            log.warning("Session timeout session=%s", session_id)
-            try:
-                await websocket.send_json(
-                    {
-                        "type": "log",
-                        "data": f"\n[系統] 已達最長執行時間（{SESSION_TIMEOUT_SEC // 60} 分鐘），自動結束。\n",
-                    }
-                )
-                await websocket.send_json({"type": "status", "data": "timeout"})
-            except Exception:
-                pass
+            warning_sent = False
+            while True:
+                await asyncio.sleep(1)
+                now = time.monotonic()
+                idle_for = now - last_activity_at
+                session_age = now - started_monotonic
+                heartbeat_age = now - last_client_seen_at
+                idle_state = _session_idle_state(idle_for)
+
+                if session_age >= SESSION_TIMEOUT_SEC:
+                    _metrics["sessions_timed_out"] += 1
+                    log.warning("Session hard timeout session=%s", session_id)
+                    await websocket.send_json(
+                        {
+                            "type": "log",
+                            "data": f"\n[系統] 已達最長執行時間（{SESSION_TIMEOUT_SEC // 60} 分鐘），自動結束。\n",
+                        }
+                    )
+                    await websocket.send_json({"type": "status", "data": "timeout"})
+                    break
+
+                if heartbeat_age >= HEARTBEAT_TIMEOUT_SEC:
+                    _metrics["sessions_heartbeat_timed_out"] += 1
+                    log.warning("Session heartbeat timeout session=%s", session_id)
+                    await websocket.send_json(
+                        {
+                            "type": "log",
+                            "data": "\n[系統] 瀏覽器已離線，自動釋放展示名額。\n",
+                        }
+                    )
+                    await websocket.send_json(
+                        {"type": "status", "data": "connection_timeout"}
+                    )
+                    break
+
+                if idle_state == "timeout":
+                    _metrics["sessions_idle_timed_out"] += 1
+                    log.info("Session idle timeout session=%s", session_id)
+                    await websocket.send_json(
+                        {
+                            "type": "log",
+                            "data": f"\n[系統] 已閒置 {IDLE_TIMEOUT_SEC // 60} 分鐘，自動結束並釋放展示名額。\n",
+                        }
+                    )
+                    await websocket.send_json(
+                        {"type": "status", "data": "idle_timeout"}
+                    )
+                    break
+
+                if idle_state == "warning" and not warning_sent:
+                    warning_sent = True
+                    await websocket.send_json(
+                        {
+                            "type": "idle_warning",
+                            "remaining_sec": max(
+                                0, int(IDLE_TIMEOUT_SEC - idle_for)
+                            ),
+                        }
+                    )
+                elif idle_state == "active" and warning_sent:
+                    warning_sent = False
+                    await websocket.send_json({"type": "idle_resumed"})
+
             try:
                 await websocket.close(code=1000)
             except Exception:
                 pass
 
-        bridge = asyncio.gather(tcp_to_ws(), ws_to_tcp())
+        tcp_task = asyncio.create_task(tcp_to_ws())
+        ws_task = asyncio.create_task(ws_to_tcp())
         watchdog = asyncio.create_task(session_watchdog())
         try:
-            await bridge
+            _, pending = await asyncio.wait(
+                {tcp_task, ws_task, watchdog},
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+            for task in pending:
+                task.cancel()
+            await asyncio.gather(*pending, return_exceptions=True)
         finally:
-            watchdog.cancel()
-            try:
-                await watchdog
-            except asyncio.CancelledError:
-                pass
+            for task in (tcp_task, ws_task, watchdog):
+                if not task.done():
+                    task.cancel()
+            await asyncio.gather(
+                tcp_task, ws_task, watchdog, return_exceptions=True
+            )
 
     finally:
         if process is not None:

static/css/player.css

@@ -752,3 +752,71 @@
 .viewport-section {
     position: relative;
 }
+
+.idle-dialog-backdrop {
+    position: fixed;
+    inset: 0;
+    z-index: 100;
+    display: grid;
+    place-items: center;
+    padding: 1.25rem;
+    background: rgba(3, 7, 18, 0.78);
+    backdrop-filter: blur(8px);
+}
+
+.idle-dialog-backdrop[hidden] {
+    display: none;
+}
+
+.idle-dialog-card {
+    width: min(420px, 100%);
+    box-sizing: border-box;
+    padding: 2rem;
+    border: 1px solid rgba(168, 85, 247, 0.35);
+    border-radius: 20px;
+    background: #111827;
+    box-shadow: 0 24px 70px rgba(0, 0, 0, 0.5);
+    color: #f9fafb;
+    text-align: center;
+}
+
+.idle-dialog-icon {
+    margin-bottom: 0.8rem;
+    font-size: 2rem;
+}
+
+.idle-dialog-card h2 {
+    margin: 0 0 0.75rem;
+    font-size: 1.45rem;
+}
+
+.idle-dialog-card p {
+    margin: 0;
+    color: #cbd5e1;
+    line-height: 1.65;
+}
+
+.idle-dialog-card strong {
+    color: #fbbf24;
+    font-variant-numeric: tabular-nums;
+}
+
+.idle-dialog-card button {
+    width: 100%;
+    margin-top: 1.4rem;
+    padding: 0.85rem 1rem;
+    border: 0;
+    border-radius: 12px;
+    background: #7c3aed;
+    color: #fff;
+    font: inherit;
+    font-weight: 700;
+    cursor: pointer;
+}
+
+.idle-dialog-card button:hover,
+.idle-dialog-card button:focus-visible {
+    background: #8b5cf6;
+    outline: 3px solid rgba(167, 139, 250, 0.35);
+    outline-offset: 3px;
+}

static/js/player.js

@@ -11,6 +11,9 @@
         const appetizeKey = cfg.appetizeKey || "";
         const viewOnly = !!cfg.viewOnly;
         const sessionTimeoutSec = cfg.sessionTimeoutSec || 900;
+        const idleWarningSec = cfg.idleWarningSec || 600;
+        const idleTimeoutSec = cfg.idleTimeoutSec || 720;
+        const heartbeatIntervalSec = cfg.heartbeatIntervalSec || 20;
 
         const viewportFrame = document.getElementById("viewport-frame");
         const focusPrompt = document.getElementById("focus-prompt-el");
@@ -21,6 +24,9 @@
         const webcamVideo = document.getElementById("webcam-video");
         const webcamCanvas = document.getElementById("webcam-canvas");
         const webcamCtx = webcamCanvas.getContext("2d");
+        const idleDialog = document.getElementById("idle-dialog");
+        const idleCountdown = document.getElementById("idle-countdown");
+        const btnContinueSession = document.getElementById("btn-continue-session");
 
         let socket = null;
         let oldUrl = null;
@@ -28,6 +34,81 @@
         let webcamInterval = null;
         let isWebcamStreaming = false;
         let isFocused = false;
+        let heartbeatTimer = null;
+        let idleCountdownTimer = null;
+        let idleDeadline = 0;
+        let lastActivitySentAt = 0;
+        let stopReason = null;
+
+        function sendSocketMessage(message) {
+            if (!socket || socket.readyState !== WebSocket.OPEN) return false;
+            socket.send(JSON.stringify(message));
+            return true;
+        }
+
+        function sendActivity(force = false) {
+            const now = Date.now();
+            if (!force && now - lastActivitySentAt < 10000) return;
+            if (sendSocketMessage({ type: "activity" })) {
+                lastActivitySentAt = now;
+                hideIdleWarning();
+            }
+        }
+
+        function startHeartbeat() {
+            stopHeartbeat();
+            heartbeatTimer = setInterval(() => {
+                sendSocketMessage({ type: "heartbeat" });
+            }, heartbeatIntervalSec * 1000);
+        }
+
+        function stopHeartbeat() {
+            if (heartbeatTimer) {
+                clearInterval(heartbeatTimer);
+                heartbeatTimer = null;
+            }
+        }
+
+        function formatCountdown(seconds) {
+            const safeSeconds = Math.max(0, Math.ceil(seconds));
+            const minutes = Math.floor(safeSeconds / 60);
+            return `${minutes}:${String(safeSeconds % 60).padStart(2, "0")}`;
+        }
+
+        function showIdleWarning(remainingSec) {
+            if (!idleDialog) return;
+            idleDeadline = Date.now() + Math.max(0, remainingSec) * 1000;
+            idleDialog.hidden = false;
+            updateIdleCountdown();
+            if (idleCountdownTimer) clearInterval(idleCountdownTimer);
+            idleCountdownTimer = setInterval(updateIdleCountdown, 250);
+            if (btnContinueSession) btnContinueSession.focus();
+        }
+
+        function updateIdleCountdown() {
+            if (!idleCountdown) return;
+            idleCountdown.textContent = formatCountdown((idleDeadline - Date.now()) / 1000);
+        }
+
+        function hideIdleWarning() {
+            if (idleDialog) idleDialog.hidden = true;
+            if (idleCountdownTimer) {
+                clearInterval(idleCountdownTimer);
+                idleCountdownTimer = null;
+            }
+        }
+
+        function setupActivityTracking() {
+            ["pointerdown", "pointermove", "keydown", "touchstart", "scroll"].forEach((eventName) => {
+                window.addEventListener(eventName, () => sendActivity(), { passive: true });
+            });
+            document.addEventListener("visibilitychange", () => {
+                if (!document.hidden) sendActivity(true);
+            });
+            if (btnContinueSession) {
+                btnContinueSession.addEventListener("click", () => sendActivity(true));
+            }
+        }
 
         // Auto-transform Scratch URLs into embed links
         function formatEmbedUrl(url) {
@@ -190,12 +271,16 @@
             
             socket = new WebSocket(wsUrl);
             socket.binaryType = "blob";
+            stopReason = null;
 
             socket.onopen = () => {
                 statusWrapper.classList.remove("status-stopped");
                 statusText.innerText = "已連線 (運作中)";
                 appendConsole("[系統] 連線成功，學生專案已啟動。\n");
-                setLoading(true, "專案執行中…", `最長執行時間約 ${Math.round(sessionTimeoutSec/60)} 分鐘`);
+                appendConsole(`[系統] 閒置 ${Math.round(idleWarningSec/60)} 分鐘會提醒，${Math.round(idleTimeoutSec/60)} 分鐘後自動釋放名額。\n`);
+                setLoading(true, "專案執行中…", `閒置 ${Math.round(idleTimeoutSec/60)} 分鐘會自動結束`);
+                sendActivity(true);
+                startHeartbeat();
                 // Hide loading once first frame or after short delay
                 setTimeout(() => setLoading(false), 2500);
             };
@@ -217,8 +302,12 @@
                         const data = JSON.parse(event.data);
                         if (data.type === "log") {
                             appendConsole(data.data);
+                        } else if (data.type === "idle_warning") {
+                            showIdleWarning(data.remaining_sec || 0);
+                        } else if (data.type === "idle_resumed") {
+                            hideIdleWarning();
                         } else if (data.type === "status") {
-                            if (data.data === "stopped" || data.data === "timeout" || data.data === "error" || data.data === "busy") {
+                            if (["stopped", "timeout", "idle_timeout", "connection_timeout", "error", "busy"].includes(data.data)) {
                                 setStoppedStatus(data.data);
                                 setLoading(false);
                             } else if (data.data === "running") {
@@ -233,8 +322,12 @@
             };
 
             socket.onclose = () => {
-                setStoppedStatus();
-                appendConsole("\n[系統] 與伺服器的通訊中斷。\n");
+                stopHeartbeat();
+                hideIdleWarning();
+                setStoppedStatus(stopReason);
+                if (!stopReason) {
+                    appendConsole("\n[系統] 與伺服器的通訊中斷。\n");
+                }
             };
 
             socket.onerror = () => {
@@ -243,10 +336,20 @@
         }
 
         function setStoppedStatus(reason) {
+            if (reason) stopReason = reason;
             statusWrapper.classList.add("status-stopped");
-            const labels = { stopped: "已停止", timeout: "逾時結束", error: "錯誤", busy: "名額已滿" };
+            const labels = {
+                stopped: "已停止",
+                timeout: "已達執行上限",
+                idle_timeout: "閒置結束",
+                connection_timeout: "連線已離開",
+                error: "錯誤",
+                busy: "名額已滿"
+            };
             statusText.innerText = labels[reason] || "已停止";
             stopWebcamStream();
+            stopHeartbeat();
+            hideIdleWarning();
             setLoading(false);
         }
 
@@ -463,8 +566,10 @@
         }
 
         window.onload = initViewport;
+        setupActivityTracking();
         window.onbeforeunload = () => {
             stopWebcamStream();
+            stopHeartbeat();
             if (socket) socket.close();
         };
 
@@ -495,4 +600,3 @@
                 if (terminalInputField) terminalInputField.focus();
             });
         }
-    

templates/player.html

@@ -136,6 +136,15 @@
         </div>
     </div>
 
+    <div class="idle-dialog-backdrop" id="idle-dialog" role="dialog" aria-modal="true" aria-labelledby="idle-dialog-title" hidden>
+        <div class="idle-dialog-card">
+            <div class="idle-dialog-icon" aria-hidden="true">⏳</div>
+            <h2 id="idle-dialog-title">還在觀看嗎？</h2>
+            <p>這個作品已一段時間沒有操作。為了讓其他家長也能使用展示名額，系統將在 <strong id="idle-countdown">2:00</strong> 後自動結束。</p>
+            <button type="button" id="btn-continue-session">繼續觀看</button>
+        </div>
+    </div>
+
     <!-- Hidden audio/video capturing items -->
     <video id="webcam-video" autoplay playsinline width="640" height="480"></video>
     <canvas id="webcam-canvas" width="640" height="480"></canvas>
@@ -153,6 +162,9 @@
             appetizeKey: {{ appetize_key|tojson }},
             viewOnly: {{ view_only|default(false)|tojson }},
             sessionTimeoutSec: {{ session_timeout_sec|default(900) }},
+            idleWarningSec: {{ idle_warning_sec|default(600) }},
+            idleTimeoutSec: {{ idle_timeout_sec|default(720) }},
+            heartbeatIntervalSec: {{ heartbeat_interval_sec|default(20) }},
             maxConcurrentRunners: {{ max_concurrent_runners|default(3) }}
         };
     </script>