How tzafon/tzafon-waypoint works
Project Type and Purpose
• This is a distributed, microservice‐based orchestration platform (“Tzafon-WayPoint”) for managing massive fleets of headless Chrome instances with near-zero cold-start latency.
• Core goal: expose a simple Python API (tzafonwright) to client applications, hide the complexity of browser lifecycle, scaling, health monitoring, and service discovery.
File Structure
• Top‐level folders:
• .github/ – CI/CD workflows
• apps/ – All source for Rust services and Python client
• deployment/ – Kubernetes/Helm/HCL deployment manifests
• Root scripts (create_release.sh, local-build.sh, simple_test.py), and Python project files (pyproject.toml)
• Under apps/:
• proto-definition/ – .proto files, TLS certs, build scripts → defines gRPC APIs
• rust-instance-container/ – Browser Container service (headless Chrome + CDP/Tzafonwright ports)
• rust-instance-manager/ – Orchestrator (instance registration, discovery, health, metrics)
• rust-shared/ – Shared Rust crates for metrics, socket gateway, utilities
• tzafonwright/ – Python client library exposing WebSocket API
README for Architectural Insights
• Communication:
• Python client ↔ Proxy (WebSocket on port 1337)
• Proxy ↔ Containers (CDP on 9222)
• All Rust components ↔ Instance Manager (gRPC over TLS)
• Key patterns: service discovery, health checking, TLS‐secured gRPC, dynamic scaling.
a. Main Components
• Clients / Python Services (external applications using tzafonwright)
• Ephemeral Browser Proxy (Rust binary)
• Instance Manager (Rust orchestrator)
• Browser Containers (Rust “instance-container” services running headless Chrome)
• Proto‐Definition & TLS Store (gRPC contracts + certificates)
• Rust‐Shared Library (utility crate used by manager & container)
• Deployment Infrastructure (Kubernetes, Helm charts, HCL/Terraform files)
b. Relationships & Data Flows
1. Client → Proxy
• WebSocket (port 1337) carrying JSON RPC or custom protocol
2. Proxy ↔ Instance Manager
• gRPC over TLS for service discovery, health/metrics
3. Instance Manager ↔ Browser Containers
• gRPC over TLS for registration, heartbeat, metrics
4. Proxy → Browser Container
• CDP proxying (port 9222) and Tzafonwright API forwarding
5. Containers register on startup with Instance Manager
c. Architectural Patterns & Principles
• Microservices: each component is a standalone binary
• Service Discovery: via Instance Manager registry
• Circuit Breaker / Health Monitoring: automatic remediation
• Secure RPC: all control-plane comms use TLS + mutual auth
• Shared Libraries: code reuse via rust-shared crate
• Separation of Concerns: proxy for client‐facing API, manager for orchestration, containers for actual work
d. Key Technologies
• Rust (tokio, tonic gRPC, Rocket/Tera for status pages)
• Python (asyncio, WebSocket client library)
• gRPC (.proto under proto-definition)
• TLS mutual‐TLS certificates
• Docker (for images built via Dockerfile.rust-builder)
• Kubernetes / Helm / Terraform (in deployment/)