How azimjohn/jprq works
Project type and purpose
• JPRQ is an open-source self-hostable tunneling service (similar to ngrok) written in Go.
• It consists of a CLI client (cli/), a server component (server/), and a static website/docs generator (website/).
• Purpose: expose local TCP/HTTP services to the public internet, optionally with a built-in HTTP debugger and custom subdomains.
File structure
Top-level:
• cli/ – the user-facing command-line client.
• server/ – the public server that accepts connections, manages tunnels, auth, and forwards traffic.
• website/ – a standalone static site (installation docs, auth portal).
• Makefile/build.sh/install.sh/jprq.service – build and deployment artifacts.
• .github/workflows/ – CI pipelines (tests, static analysis, vulnerability scanning).
Patterns & modules:
• cli/debugger/ – embedded web UI assets for HTTP debugging.
• server/config/, server/events/, server/github/ – configuration, internal event bus, GitHub-based auth/invite logic.
• server/server/ – TCP server accepting client connections over TLS.
• server/tunnel/ – HTTP and TCP tunnel implementations forwarding public traffic into client tunnels.
Deployment artifacts:
• jprq.service – systemd unit to run the server.
• install.sh, build.sh, Makefile – scripts to build and install both client and server.
README for insights
• Describes use cases (HTTP, SSH, custom domains, debugger).
• References an auth flow via jprq auth <token> (server must validate tokens via GitHub).
• Mentions a members-only hosted service but emphasizes self-hosting.
1. CLI Client
2. Public Tunnel Server
– Control Plane (HTTP/gRPC for auth, session management)
– Data Plane (TCP server accepting tunnel connections)
– GitHub Auth Service (external API)
– Internal Event Bus
3. End-User Local Server (e.g., localhost:3000)
4. Optional HTTP Debugger UI (hosted by CLI, proxied via server)
5. Static Website (optional docs site, website/)
6. Build & CI pipeline (GitHub Actions, Makefile)
b. Relationships and interactions:
• CLI → Server (Control Plane): authenticate via API, negotiate tunnel parameters (port, subdomain).
• CLI ↔ Server (Data Plane): maintain a long-lived TLS/TCP connection for forwarding traffic.
• Server → Local Server: on incoming public request, forward over the CLI’s tunnel to the user’s local app.
• Debugger: CLI spins up a local HTTP server for debug UI; server forwards debug HTTP events back to this UI.
• Server → GitHub API: validate membership tokens for hosted service.
c. Architectural patterns & principles:
• Separation of control plane vs. data plane.
• Modular Go packages (configuration, events bus, tunnel implementations).
• Single binary distribution (embedded static assets).
• Self-hosting vs. SaaS duality (same codebase, different deployments).
d. Key technologies & libraries:
• Go modules (go.mod), standard net/http, crypto/tls.
• Tailwind CSS + static HTML/JS for the debugger UI.
• systemd service file for server deployment.
• GitHub Actions workflows for CI/CD.
[ ] Show persistent TCP connection: Server Data Plane ↔ CLI Tunnel client.
[ ] Optionally note the website/docs server as a standalone process or static site host.
[ ] Include build/deploy artifacts (Makefile, Dockerfile or systemd) in a corner to illustrate CI/CD.