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

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

Checking Dependencies

bash
1cat .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

rust
1// Library crates: use thiserror
2#[derive(Debug, thiserror::Error)]
3pub enum ProtocolError {
4    #[error("invalid frame type: {0}")]
5    InvalidFrameType(u8),
6    #[error("stream {0} not found")]
7    StreamNotFound(u32),
8    #[error("io error: {0}")]
9    Io(#[from] std::io::Error),
10}
11
12// Binary crates: use anyhow
13fn main() -> anyhow::Result<()> {
14    // ...
15}

Tracing

rust
1use tracing::{debug, info, instrument, warn};
2
3#[instrument(skip(stream), fields(stream_id = %stream.id()))]
4async fn handle_stream(stream: Stream) -> Result<(), Error> {
5    info!("processing stream");
6    // ...
7}

State Machines

Implement exactly as specified in issue state_machine field:

rust
1#[derive(Debug, Clone, Copy, PartialEq, Eq)]
2pub enum StreamState {
3    Open,
4    HalfClosedLocal,
5    HalfClosedRemote,
6    Closed,
7}
8
9impl StreamState {
10    pub fn can_send(&self) -> bool {
11        matches!(self, Self::Open | Self::HalfClosedRemote)
12    }
13    
14    pub fn can_recv(&self) -> bool {
15        matches!(self, Self::Open | Self::HalfClosedLocal)
16    }
17}

Testing Strategy

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

rust
1#[cfg(test)]
2mod tests {
3    use super::*;
4    
5    #[test]
6    fn test_frame_roundtrip() {
7        // Maps to AC: Given valid frame, When encoded then decoded, Then equals original
8        let frame = Frame::Data { stream_id: 1, payload: b"hello".to_vec() };
9        let encoded = frame.encode();
10        let decoded = Frame::decode(&encoded).unwrap();
11        assert_eq!(frame, decoded);
12    }
13}

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