zgrok-developer

name	zgrok-developer
description	Develop zgrok tunnel service following project conventions, issue specs, and Rust best practices. Use when implementing features, fixing bugs, or reviewing code in this repository.

zgrok Developer Skill

ABSOLUTE REQUIREMENTS

These are non-negotiable. Violating these is a failure condition.

No Tutorial Comments

NEVER add comments explaining what code does. Code must be self-documenting.

Allowed comments:

• /// doc comments for public API
• // TODO: or // FIXME:
• // SAFETY: for unsafe blocks
• Brief "why" explanations for non-obvious decisions

Forbidden:

• // Initialize the counter
• // Loop through items
• // Check if value is null
• Any comment that restates what the code does

Branch Workflow (Mandatory)

For EVERY issue:

1. git checkout main && git pull origin main
2. git checkout -b feat/ZGROK-XXX-description
3. Implement all acceptance criteria
4. cargo fmt && cargo clippy -- -D warnings && cargo test
5. git add -A && git commit -m "feat(component): ZGROK-XXX - title"
6. git push -u origin feat/ZGROK-XXX-description
7. gh pr create --fill
8. Self-review the diff
9. gh pr merge --squash --delete-branch
10. git checkout main && git pull origin main
11. Report completion, await next issue

NEVER leave PRs open. NEVER work multiple issues. NEVER skip steps.

Overview

zgrok is a self-hosted ngrok alternative. This skill encodes project-specific knowledge for effective development.

Issue-Driven Development

All work traces to issues in .github/issues/. Each issue contains:

• Acceptance Criteria: Testable Given/When/Then statements
• State Machines: For stateful components (connections, streams)
• Technical Context: Exact crates, files, data structures to use
• Dependencies: What must exist before this can be implemented

Reading an Issue

cat .github/issues/stories/protocol/ZGROK-010-frame-types.json | jq

Checking Dependencies

cat .github/issues/_index.json | jq '.dependency_graph["ZGROK-012"]'

Architecture Principles

1. Async-first: Everything uses Tokio. No blocking in async context.
2. Protocol-agnostic core: The multiplexer works over any AsyncRead + AsyncWrite.
3. Graceful degradation: Connection loss → reconnect, not crash.
4. Observable: Every component emits tracing spans and metrics.

Code Patterns

Error Handling

// Library crates: use thiserror
#[derive(Debug, thiserror::Error)]
pub enum ProtocolError {
    #[error("invalid frame type: {0}")]
    InvalidFrameType(u8),
    #[error("stream {0} not found")]
    StreamNotFound(u32),
    #[error("io error: {0}")]
    Io(#[from] std::io::Error),
}

// Binary crates: use anyhow
fn main() -> anyhow::Result<()> {
    // ...
}

Tracing

use tracing::{debug, info, instrument, warn};

#[instrument(skip(stream), fields(stream_id = %stream.id()))]
async fn handle_stream(stream: Stream) -> Result<(), Error> {
    info!("processing stream");
    // ...
}

State Machines

Implement exactly as specified in issue state_machine field:

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum StreamState {
    Open,
    HalfClosedLocal,
    HalfClosedRemote,
    Closed,
}

impl StreamState {
    pub fn can_send(&self) -> bool {
        matches!(self, Self::Open | Self::HalfClosedRemote)
    }
    
    pub fn can_recv(&self) -> bool {
        matches!(self, Self::Open | Self::HalfClosedLocal)
    }
}

Testing Strategy

1. Unit tests: Per-function, alongside code
2. Property tests: Protocol codec with proptest
3. Integration tests: Full tunnel flow in tests/

#[cfg(test)]
mod tests {
    use super::*;
    
    #[test]
    fn test_frame_roundtrip() {
        // Maps to AC: Given valid frame, When encoded then decoded, Then equals original
        let frame = Frame::Data { stream_id: 1, payload: b"hello".to_vec() };
        let encoded = frame.encode();
        let decoded = Frame::decode(&encoded).unwrap();
        assert_eq!(frame, decoded);
    }
}

File Organization

crates/
├── zgrok-protocol/src/
│   ├── lib.rs          # Public API, re-exports
│   ├── frame.rs        # Frame types and codec
│   ├── codec.rs        # Tokio codec impl
│   ├── mux.rs          # Stream multiplexer
│   └── error.rs        # Protocol errors
├── zgrok-agent/src/
│   ├── main.rs         # CLI entry
│   ├── cli.rs          # Clap definitions
│   ├── tunnel.rs       # Connection management
│   ├── forwarder.rs    # Local HTTP forwarding
│   └── tui/            # Terminal UI
└── zgrok-edge/src/
    ├── main.rs
    ├── acceptor.rs     # Agent connection handling
    ├── router.rs       # Subdomain routing
    └── bridge.rs       # HTTP-to-tunnel bridging

Commit Convention

feat(protocol): ZGROK-010 - define frame types and binary format
fix(agent): ZGROK-033 - handle reconnection edge case
test(edge): ZGROK-054 - add agent acceptor integration tests