# Phase 3: Direct Proxy Creation with Validation

**Status:** ⬜ Not Started
**Parent plan:** [PLAN.md](./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
<!-- Filled in by the implementation agent after completing this phase. -->