agentskills.codes
DE

debug_stream

by c4softwareCodingSource

A debugging guide for stream distribution, focusing on client connection issues, buffer management, and network performance.

DebuggingMonitoringRust

Install

mkdir -p .claude/skills/debug-stream && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/13950" && unzip -o skill.zip -d .claude/skills/debug-stream && rm skill.zip

Installs to .claude/skills/debug-stream

Activation

This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.

Guide for debugging stream distribution and client connection issues
68 charsno explicit “when” trigger
Advanced

Key capabilities

  • →Debug stream distribution issues
  • →Diagnose client connection problems
  • →Analyze `src/client_manager.rs` for dispatch loop issues
  • →Check `src/main.rs` for channel capacity and error handling
  • →Verify `Arc<AtomicUsize>` usage for client count
  • →Use `curl` to verify stream consumption

How it works

The skill helps debug stream distribution and client connection issues by analyzing the Pub/Sub model in `src/client_manager.rs` and `src/main.rs` for common problems like lagging receivers or TCP Head-of-Line blocking.

Inputs & outputs

You give it
Symptoms like clients disconnecting immediately, stream stuttering, or no stats update
You get back
Analysis and potential fixes for stream and client issues

When to use debug_stream

  • →Fixing disconnected clients
  • →Reducing stream latency
  • →Debugging broadcast buffers
  • →Resolving stream stuttering

About this skill

Analyze Stream & Clients

This skill helps you debug issues in src/client_manager.rs and src/main.rs, specifically regarding multiple clients, network drops, or chunk distribution.

🧠 Context

The streaming architecture is a Pub/Sub model:

  1. Publisher: The Encoder loop sends H.264 NAL units (chunks) to a tokio::sync::broadcast channel.
  2. Subscriber: Each HTTP request to /ws (or root) spawns a subscriber that listens to this channel and yields bytes to the TCP socket.

🛠️ Common Issues

1. Clients Disconnecting Immediately

Symptom: Browser opens, then closes connection or shows error. Cause:

  • Lagging Receiver: tokio::sync::broadcast returns RecvError::Lagged if the client reads too slowly and the buffer fills up.
  • Header Mismatch: Client expects Content-Type: video/h264 or specific CORS headers.

Fix:

  • Increase channel capacity in main.rs (default might be 16 or 32).
  • Handle Lagged error gracefully (currently it might drop the stream).

2. Stream Stuttering

Cause: Network jitter or TCP Head-of-Line blocking. Analysis:

  • Check client_manager.rs dispatch loop.
  • Ensure we are sending "small enough" chunks, or Chunked transfer encoding is working correctly.

3. No Stats Update

Symptom: /stats returns 0 active clients despite opened tabs. Cause: The ClientManager reference counting might be broken or the drop guard is not firing. Check: Look for Arc<AtomicUsize> usage for connected client count.

🚀 Key Code Paths

src/client_manager.rs

  • ClientManager struct: Holds the broadcast sender.
  • subscribe(): Returns a Receiver for a new client.

src/main.rs (Handler)

  • stream_handler:
    • Calls client_manager.subscribe().
    • Loops over rx.recv().
    • Yields Bytes to the Axum body body stream.

🧪 Verification

Use curl to consume the stream without a browser:

curl -v http://localhost:8080 > /dev/null

Watch the server logs for "New client connected" / "Client disconnected".

When not to use it

  • →When the issue is not related to stream distribution or client connections
  • →When the problem is outside `src/client_manager.rs` and `src/main.rs`

Limitations

  • →Specific to issues in `src/client_manager.rs` and `src/main.rs`
  • →Focuses on multiple clients, network drops, or chunk distribution
  • →Assumes a Pub/Sub streaming architecture

How it compares

This skill provides a targeted debugging guide for stream distribution and client connection issues within a specific Rust architecture, unlike general network troubleshooting.

Compared to similar skills

debug_stream side by side with the closest alternatives in the catalog.

SkillInstallsUpdatedSafetyDifficulty
debug_stream (this skill)06moReviewAdvanced
memory-safety-patterns44moNo flagsAdvanced
debug-cli18moReviewIntermediate
fix-clippy36moNo flagsBeginner

Try saying

Example prompts that trigger this skill in your AI assistant.

You might also like

memory-safety-patterns

sickn33

Implement memory-safe programming with RAII, ownership, smart pointers, and resource management across Rust, C++, and C. Use when writing safe systems code, managing resources, or preventing memory bugs.

415

debug-cli

antinomyhq

Use when users need to debug, modify, or extend the code-forge application's CLI commands, argument parsing, or CLI behavior. This includes adding new commands, fixing CLI bugs, updating command options, or troubleshooting CLI-related issues.

117

fix-clippy

quickwit-oss

Fix all clippy lint warnings in the project

315

debug-lldb

regenrek

Capture and analyze thread backtraces with LLDB/GDB to debug hangs, deadlocks, UI freezes, IPC stalls, or high-CPU loops across any language or project. Use when an app becomes unresponsive, switching contexts stalls, or you need thread stacks to locate lock inversion or blocking calls.

116

handling-rust-errors

hashintel

HASH error handling patterns using error-stack crate. Use when working with Result types, Report types, defining custom errors, propagating errors with change_context, adding context with attach, implementing Error trait, or documenting error conditions in Rust code.

46

rust-router

actionbook

CRITICAL: Use for ALL Rust questions including errors, design, and coding. HIGHEST PRIORITY for: 比较, 对比, compare, vs, versus, 区别, difference, 最佳实践, best practice, tokio vs, async-std vs, 比较 tokio, 比较 async, Triggers on: Rust, cargo, rustc, crate, Cargo.toml, 意图分析, 问题分析, 语义分析, analyze intent, question analysis, compile error, borrow error, lifetime error, ownership error, type error, trait error, value moved, cannot borrow, does not live long enough, mismatched types, not satisfied, E0382, E0597, E0277, E0308, E0499, E0502, E0596, async, await, Send, Sync, tokio, concurrency, error handling, 编译错误, compile error, 所有权, ownership, 借用, borrow, 生命周期, lifetime, 类型错误, type error, 异步, async, 并发, concurrency, 错误处理, error handling, 问题, problem, question, 怎么用, how to use, 如何, how to, 为什么, why, 什么是, what is, 帮我写, help me write, 实现, implement, 解释, explain

36

Search skills

Search the agent skills registry