tiny-forge/plans/observability-proxy-mgmt/phase-3-proxy-creation.md

Phase 3: Direct Proxy Creation with Validation

Status: ⬜ Not Started Parent plan: PLAN.md Domain: backend

Objective

Implement standalone proxy creation with a multi-step validation pipeline that checks destination reachability, and periodic health monitoring for all standalone proxies.

Tasks

• Task 1: Create internal/proxy/validator.go — validation pipeline:
  • URL/port syntax validation
  • DNS resolution check
  • TCP port reachability (net.DialTimeout, 5s)
  • HTTP health probe (GET to destination, 10s timeout)
  • Returns structured ValidationResult with per-step pass/fail and diagnostic hints
• Task 2: Create internal/proxy/hints.go — diagnostic hint generator:
  • DNS failure → "Domain cannot be resolved. Check DNS settings or use an IP address."
  • TCP refused → "Port {port} is not accepting connections. Check if the service is running and the port is correct."
  • TCP timeout → "Connection timed out. Possible firewall blocking. Check network/firewall rules."
  • Host unreachable → "Host is not reachable. Verify the IP address and network connectivity."
  • HTTP error → "Service responded with HTTP {status}. The service may not be healthy."
• Task 3: Create internal/proxy/manager.go — proxy lifecycle:
  • CreateProxy: validate destination, create NPM proxy host (using npm.Client), assign SSL cert from settings, save to standalone_proxies table
  • UpdateProxy: re-validate, update NPM proxy host, update store
  • DeleteProxy: remove NPM proxy host, remove from store
  • GetProxy/ListProxies: read from store with health status
• Task 4: Create internal/proxy/health.go — periodic health monitor:
  • Cron job that checks all standalone proxies
  • HTTP GET to destination URL/port
  • Updates health_status (healthy/unhealthy/unknown) and health_checked_at in store
  • Emits event_log on status change (healthy→unhealthy or vice versa)
• Task 5: Add API endpoints:
  • POST /api/proxies/validate — run validation without creating
  • POST /api/proxies — create standalone proxy
  • GET /api/proxies — list standalone proxies
  • GET /api/proxies/{id} — get single proxy
  • PUT /api/proxies/{id} — update proxy
  • DELETE /api/proxies/{id} — delete proxy
  • GET /api/proxies/all — merged view: standalone + deploy-managed proxies (for Phase 4 UI)
• Task 6: Wire health monitor cron job in main.go
• Task 7: Add frontend API functions in api.ts: validateProxy, createProxy, listProxies, getProxy, updateProxy, deleteProxy, listAllProxies
• Task 8: Add frontend types: ValidationResult, ValidationStep, ProxyHealthStatus

Files to Modify/Create

• internal/proxy/validator.go — NEW: Validation pipeline
• internal/proxy/hints.go — NEW: Diagnostic hints
• internal/proxy/manager.go — NEW: Proxy lifecycle management
• internal/proxy/health.go — NEW: Health monitoring
• internal/api/router.go — Mount proxy routes
• internal/api/proxy.go — NEW: Proxy HTTP handlers
• cmd/server/main.go — Wire proxy manager and health monitor
• web/src/lib/types.ts — Add ValidationResult, ProxyHealthStatus types
• web/src/lib/api.ts — Add proxy API functions

Acceptance Criteria

• Validation pipeline returns structured results with specific failure hints
• POST /api/proxies/validate runs full check without side effects
• Proxy creation creates NPM proxy host with SSL cert from global settings
• Health monitor runs periodically and updates proxy status
• Events emitted on health status changes
• GET /api/proxies/all merges standalone and deploy-managed proxy data
• Build passes, existing tests pass

Notes

• Validation should be fast (short timeouts) — user waits for results
• Health monitor interval: every 5 minutes (configurable later)
• For /api/proxies/all: query NPM for all proxy hosts, join with instances table for managed proxies, join with standalone_proxies for standalone ones
• SSL cert auto-assigned from settings.ssl_certificate_id
• Consider: proxy domain must be unique across both standalone and managed proxies

Review Checklist

• All tasks completed
• Code follows project conventions
• No unintended side effects
• Build passes
• Tests pass (new + existing)

Handoff to Next Phase