afloresc/ipquery

Purpose and runtime

IPQuery is a Go HTTP microservice that returns normalized IP intelligence, including ISP, geolocation, and risk data. It exposes a versioned REST API, fronts an external IP-information provider, caches results in process memory, and is containerizable for platforms such as Render.

Entry point and composition

cmd/server/main.go is the application entry point. It is responsible for process startup and wiring the HTTP router, IP-info service/provider, logging, and server configuration. The service is intended to bind using environment-provided port configuration, including Render’s PORT.

Paths:

• cmd/server/main.go

• Dockerfile

HTTP boundary and API routing

The HTTP layer owns public endpoints and request/response behavior:

• GET /v1/health provides liveness/operational status.

• GET /v1/ip/{ip} resolves intelligence for the requested IP.

Routing and HTTP-specific concerns are separated from domain lookup logic, so handlers translate inbound requests into service calls and serialize JSON responses/errors.

Paths:

• internal/handlers/routes.go

• internal/handlers/http.go

Request protection and middleware pipeline

Requests pass through operational and security middleware before reaching handlers. README-defined controls include structured request logging, panic recovery, strict timeouts, rate limiting, CORS restrictions, security headers, and client-IP handling via X-Forwarded-For protection. This is the principal trust boundary between internet-facing traffic and lookup execution.

Paths:

• internal/handlers/routes.go

• internal/logger/middleware.go

IP intelligence domain service

The IP-info layer contains the core lookup orchestration: it validates/uses the requested IP, checks cached data, calls the provider on a miss, and returns a unified result shape to handlers. This isolates external-provider-specific behavior from the API contract.

Paths:

• internal/ipinfo/service.go

• internal/ipinfo/provider.go

Caching and resilience boundary

Lookup results are cached in memory using sync.Map with a one-hour lifetime, reducing latency and external API dependence. Provider calls are guarded by strict timeouts; failures are surfaced through the HTTP layer rather than destabilizing the process. Cache state is local to one service instance and is lost on restart or not shared across replicas.

Paths:

• internal/ipinfo/service.go

• internal/ipinfo/provider.go

Observability and deployment

Logging is structured JSON using Go’s slog, implemented as HTTP middleware for cloud-log ingestion and request tracing/diagnosis. The Docker build artifact supports container deployment; Render is the documented target and consumes the health endpoint for service checks.

Paths:

• internal/logger/middleware.go

• Dockerfile

• cmd/server/main.go