ping-gopher

module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 23, 2026 License: MIT

README ΒΆ

PingGopher πŸΉπŸ“‘

Modern, High-Performance Uptime & Synthetic Monitoring SaaS powered by gopher-queue

CI Go Version gopher-queue License

PingGopher is a standalone, full-stack Uptime & Synthetic Monitoring SaaS built with Go and powered by the distributed task engine gopher-queue. Engineered with a Modular Monolith ("Deploy Any Role") architecture, PingGopher can run as an all-in-one process or scale horizontally by deploying dedicated API, Worker, and Scheduler roles from a single binary.


πŸ“Έ Screenshots & Product Previews

1. Main Web Dashboard (/)

PingGopher Dashboard Preview

2. Probe Response Latency & Execution Logs Modal

3. Hosted Public Status Page (/status.html)

PingGopher Public Status Page

4. Official Terminal CLI Control Tool (pinggopher-cli)

PingGopher CLI Tool Preview


πŸ“‚ Project Structure

ping-gopher/
β”œβ”€β”€ .github/workflows/    # Automated CI/CD build & test workflows
β”œβ”€β”€ .agents/              # Workspace rules & agent instructions
β”œβ”€β”€ assets/               # Repository preview screenshots & media assets
β”œβ”€β”€ bin/                  # Pre-compiled cross-platform static binaries
β”œβ”€β”€ cmd/
β”‚   β”œβ”€β”€ pinggopher/       # Main server binary entrypoint & multi-role launcher
β”‚   └── pinggopher-cli/   # Official CLI tool client (terminal control)
β”œβ”€β”€ internal/
β”‚   β”œβ”€β”€ api/              # REST API handlers, router & middleware
β”‚   β”œβ”€β”€ auth/             # Password security (Bcrypt) & JWT token engine
β”‚   β”œβ”€β”€ config/           # Environment variables & CLI flags parser
β”‚   β”œβ”€β”€ db/               # GORM database layer, models & migrations
β”‚   β”œβ”€β”€ notifier/         # Webhook & multi-channel alert pipeline
β”‚   β”œβ”€β”€ scheduler/        # Background monitor check promoter loop
β”‚   └── worker/           # Synthetic probe execution engine (HTTP/SSL)
β”œβ”€β”€ web/                  # Glassmorphic SPA frontend & Go static embedder
β”œβ”€β”€ Dockerfile            # Multi-stage production container build
β”œβ”€β”€ docker-compose.yml    # Multi-container orchestration (PingGopher + Redis)
β”œβ”€β”€ Makefile              # Development build & execution shortcuts
└── README.md             # Master project documentation

πŸ›οΈ Architecture & System Design

PingGopher uses a Modular Monolith pattern with decoupling between domain packages (internal/db, internal/config, internal/api, internal/worker, internal/notifier).

                    +------------------------------------+
                    |  REST API / Web Dashboard Client   |
                    +------------------------------------+
                                      |
                                      v
                    +------------------------------------+
                    |    pinggopher (--role=api)         |
                    +------------------------------------+
                                      |
                                      v
     +------------------------------------------------------------------+
     |                 Database Layer (SQLite / PostgreSQL)              |
     |           Users | Monitors | PingLogs | Incidents                |
     +------------------------------------------------------------------+
                                      ^
                                      |
    +---------------------------------+---------------------------------+
    |                                                                   |
    v                                                                   v
+------------------------------------+              +------------------------------------+
|   pinggopher (--role=scheduler)    |              |     pinggopher (--role=worker)     |
|   Enqueues Monitor Probes          |              |     Executes Probes via           |
|   into gopher-queue                |              |     gopher-queue Task Pools      |
+------------------------------------+              +------------------------------------+
                  \                                                   /
                   \                                                 /
                    +-----------------------------------------------+
                    |     gopher-queue Broker (Redis 7.0+)          |
                    |     Atomic Leasing, Retries, Watchdog, DLQ    |
                    +-----------------------------------------------+
🎭 Deploy Any Role Strategy

Run any node type using runtime CLI flags or environment variables:

  • pinggopher --role=all: All-in-one development node running API, Scheduler, and Worker.
  • pinggopher --role=api: Dedicated HTTP REST API & Web Dashboard node.
  • pinggopher --role=worker: Dedicated background probe execution worker.
  • pinggopher --role=scheduler: Dedicated monitor promoter loop enqueuing jobs to gopher-queue.

✨ Key Features

  • 🌐 External Synthetic Uptime Monitoring: Measures HTTP response codes, latency (ms), and SSL certificate expiration.
  • ⚑ Powered by gopher-queue: Leverages server-side Redis Lua scripts, atomic leasing, watchdog supervisor failover, and exponential retries.
  • πŸ›‘οΈ Anti-Alert Fatigue: Smart escalation logic using retry windows before dispatching alerts.
  • πŸ“Š Multi-Tenant Data Models: Built-in GORM schema for Users, Monitors, Latency Logs, and Outage Incidents.
  • πŸš€ Zero-Dependency Local Storage: Runs out of the box with embedded CGO-free SQLite for local development and PostgreSQL support for production.

πŸ’» Official CLI Tool (pinggopher-cli)

PingGopher includes an official command-line client for terminal-based tenant authentication, monitor CRUD management, public status checking, and probe latency inspection.

PingGopher CLI Tool Preview

πŸ“₯ Installation via go install
go install github.com/SirZeck/ping-gopher/cmd/pinggopher-cli@latest

[!TIP] Executing pinggopher-cli from any terminal window: Go installs binaries into $(go env GOPATH)/bin (%USERPROFILE%\go\bin on Windows).

  • Windows (PowerShell): [Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:USERPROFILE\go\bin", "User")
  • Linux / macOS: export PATH=$PATH:$(go env GOPATH)/bin (add to ~/.bashrc or ~/.zshrc).
⚑ Terminal Usage Examples
# 1. Register a new tenant account and save session token
pinggopher-cli signup --url http://localhost:8080 --email newuser@pinggopher.io --password SecretPassword123!

# 2. Or authenticate an existing account
pinggopher-cli login --url http://localhost:8080 --email admin@pinggopher.io --password SecretPassword123!

# 2. View public system operational health status
pinggopher-cli status

# 3. List active monitor targets in formatted ASCII table
pinggopher-cli monitor list

# 4. Add a new target monitor directly from the terminal
pinggopher-cli monitor add --name "Production API" --url "https://api.example.com/health" --interval 30

# 5. Inspect probe latency response history logs
pinggopher-cli logs --id <MONITOR_ID> --limit 20

Read the full cmd/pinggopher-cli/README.md for detailed CLI documentation.


πŸš€ Quickstart

Launch PingGopher and Redis broker with a single command:

docker compose up -d --build

Verify application status:

docker compose logs -f pinggopher

2. Build & Run Locally
Prerequisites
  • Go 1.22+
  • Redis 7.0+ running on localhost:6379 (required for gopher-queue worker pool)
Build Binary
make build
# Produces bin/pinggopher.exe
Run All-in-One Node
make run-all
# Or run manually:
./bin/pinggopher.exe --role=all

βš™οΈ Configuration

Configurations can be set via command-line flags or environment variables:

Flag Environment Variable Default Description
--role ROLE all Service role (all, api, worker, scheduler)
--port PORT 8080 HTTP API server port
--db DB_PATH pinggopher.db SQLite database file path or Postgres DSN
--redis REDIS_ADDR localhost:6379 Redis broker address for gopher-queue
--jwt-secret JWT_SECRET pinggopher-secret... Secret key for JWT token signing

πŸ›‘οΈ Security, Auditing & Quality Assurance

PingGopher enforces a rigorous Pre-Launch Code Auditing & Technical Remediation system. Every major release undergoes automated and manual security reviews covering Server-Side Request Forgery (SSRF) defense, multi-tenant isolation, database WAL concurrency, memory DoS protection, and graceful process lifecycles.

πŸ“„ Versioned Audit & Remediation Records
⚑ Engineering Standards & Hardening Guidelines
  • SSRF Defense Engine: All outgoing probe targets and webhooks are validated against private, loopback, and cloud IMDS CIDRs (169.254.169.254).
  • SQLite Concurrency & WAL: DSN parameters enable Write-Ahead Logging (WAL mode), 5000ms busy timeouts, and SetMaxOpenConns(1) connection pool limits to eliminate database lock panics.
  • Multi-Tenant Data Isolation: All API endpoints and public status pages query data strictly scoped to tenant IDs.
  • Graceful Lifecycle Shutdown: HTTP servers and scheduler loops listen for OS signals (SIGINT/SIGTERM) and drain connections cleanly via server.Shutdown(ctx).
  • Container Hardening: Docker builds run under a non-privileged system user (USER appuser) with native container HEALTHCHECK probes.

🀝 Contributing

Contributions are welcome! Please check our Contributing Guide for setup steps and pull request guidelines.


πŸ“„ License

Distributed under the MIT License. See LICENSE for details.

Directories ΒΆ

Path Synopsis
cmd
pinggopher command
pinggopher-cli command
internal
api
db

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL