Alpamon Agent Refactoring

[geunwoonoh]

🎯 Objectives

Refactor Alpamon into a stable and maintainable system agent. Apply the Agent Pattern proven by successful agents.

Key Improvements

• ✅ Goroutine Management: Unlimited creation → Limited pool (prevent memory leaks)
• ✅ God Object Resolution: command.go 2,189 lines → Split into handlers under 200 lines each
• ✅ Context Propagation: Non-cancellable operations → All operations cancellable (graceful shutdown)
• ✅ Testability: Massive switch statement → Mockable Handler interfaces

📊 Current Problems

1. God Object Anti-pattern

• pkg/runner/command.go: 2,189 lines (41% of entire runner package)
• 14+ responsibilities mixed in a single file
• Untestable massive switch statement

2. Goroutine Memory Leak Risk

// pkg/runner/client.go:230-231
case "command":
    commandRunner := NewCommandRunner(...)
    go commandRunner.Run()  // ❌ Unlimited goroutine creation

• No limit on concurrent commands
• Goroutine leak if command hangs
• No context propagation = cannot cancel

3. Circular Dependencies

• runner → utils → runner (via function pointers)
• 10+ global variables (utils/firewall.go)

🚀 Progress

• Phase 1: Goroutine Pool + Context Management
• Phase 2: Command Handler Separation
• Phase 3: Firewall Refactoring
• Phase 4: Transport Layer Separation
• Phase 5: Testing & Validation

📈 Success Metrics

Metric	Current	Target	Improvement
Max File Size	2,189 lines	< 300 lines	86% reduction
Goroutine Management	Unlimited	Pool limit (10)	Memory stabilization
Context Propagation	0%	100%	Full coverage
Test Coverage	Nearly impossible	80%+	Mock-based testing

🏗️ New Architecture

Agent Pattern-based Structure

alpamon/
├── cmd/alpamon/           # CLI entry point
├── pkg/
│   ├── agent/            # Core agent runtime
│   │   ├── agent.go      # Agent orchestration
│   │   ├── lifecycle.go  # Start/stop/restart management
│   │   └── context.go    # Context management
│   ├── executor/         # Command execution (runner refactored)
│   │   ├── executor.go   # Base executor + goroutine pool
│   │   ├── handlers/     # Command handlers (command.go decomposed)
│   │   │   ├── handler.go    # Handler interface
│   │   │   ├── system.go     # upgrade, restart, reboot
│   │   │   ├── user.go       # User/group management
│   │   │   ├── firewall.go   # Firewall operations
│   │   │   ├── file.go       # File upload/download
│   │   │   └── shell.go      # Shell command execution
│   │   └── pool.go       # Worker Pool implementation
│   ├── transport/        # Communication layer (separated from runner)
│   │   ├── websocket.go  # WebSocket client
│   │   ├── protocol.go   # Protocol definition
│   │   └── dispatcher.go # Command dispatcher
│   └── collector/        # Metrics collection (keep existing - excellent)
└── internal/             # Internal packages
    ├── pool/            # Goroutine pool implementation
    └── shutdown/        # Graceful shutdown

• This architecture is subject to change based on future development.

Core Design Patterns

• Handler Pattern: Independent handler per command type
• Object Pool: Goroutine reuse and memory management
• Strategy Pattern: Firewall backend selection (iptables/nftables)
• Registry Pattern: Dynamic handler registration and management

✅ Success Criteria

Must-Achieve Goals

• Max 300 lines per file (current: 2,189 lines)
• Zero goroutine leaks (verified by tests)
• 100% context cancellation support (all long-running operations)
• 80%+ unit test coverage (each handler independently testable)
• Memory < 50MB (idle state)
• Startup time < 1 second

Safety Guarantees

• 100% existing functionality preserved (backward compatible)
• Canary testing before production deployment
• Rollback plan ready (tag: v1.0-pre-refactor)