How omarahm3/squirrel works
Project type and purpose
• This is a distributed, real-time log-streaming system composed of two Go applications:
a) squirrel (client/CLI) – a command-line tool for broadcasting or listening to stdout streams.
b) squirreld (server/daemon) – an HTTP & WebSocket server that routes messages between broadcasters and subscribers.
• Use case: pipe any command’s stdout into squirrel to obtain a shareable link or ID, then view logs in a browser or another CLI instance in real time.
File structure
Top-level directories and role:
• cmd/
• squirrel (CLI entry point)
• squirreld (server entry point)
• client/
• Implementation of client logic (options parsing, HTTP/WebSocket client, piping)
• server/
• HTTP routes, WebSocket hub, message definitions, HTML template for web UI
• internal/pkg/common/
• Shared structs and utilities (message formats, templates, helpers)
• Dockerfile.squirrel & Dockerfile.squirreld
• CI/CD and release configs (.github/, Makefile, goreleaser.yaml)
README for additional insights
• The server is a pure in-memory WebSocket hub—no database or durable storage.
• Two modes for the client: broadcasting (default) and listening (-l/--listen).
• Configuration via flags or environment variables for both client and server.
• The web UI is served from server/view/index.html and connects back over WebSocket.
Main components & interactions
a. Client (CLI)
• Mode: Broadcaster → opens WebSocket to server, streams stdin as WebSocket messages.
• Mode: Listener → opens WebSocket using peer ID, displays incoming messages or pipes to stdout.
b. Server (squirreld)
• HTTP Server on port (default 3000):
• Serves web UI (/client/{id}) and health routes.
• WebSocket Hub (hub.go):
• Maintains maps of broadcaster→subscribers.
• Routes messages from broadcasters to all connected subscribers.
c. Browser (Web UI)
• Connects to server’s WebSocket endpoint, displays incoming log lines in real time.
d. CI/CD & Packaging
• GoReleaser, Docker images for both apps, GitHub workflows.
Relationships & data flows
1. User pipes stdout → squirrel CLI
→ CLI registers with server via HTTP or WS (handshake).
→ WebSocket connection established.
→ CLI sends each line as a JSON Message.
2. Server hub receives message
→ Broadcasts to all listening clients and any open web UI sessions.
3. Browser / squirrel CLI listener
→ Connects via WebSocket using the ID.
→ Receives JSON messages, renders to screen.
Important architectural patterns
• Pub/Sub over WebSocket: one publisher, many subscribers.
• Hexagonal/Internal packages: shared message types and utilities in internal/pkg/common.
• Separation of concerns:
• cmd/ for wiring & CLI flags
• client/ and server/ for core logic
• view/ for UI template
• Concurrency: Go routines and channels to manage connections and message distribution.