first commit

README.md

@@ -0,0 +1,75 @@
+# IP Echo
+
+A small Go web service like `ifconfig.me`: call it from a browser, curl, or another service and it tells you what IP address the server sees.
+
+## What It Teaches
+
+- `net/http` routing with the standard library.
+- Reading configuration from environment variables.
+- Extracting a client IP safely from `RemoteAddr`.
+- Optional proxy header support for deployments behind Nginx, Caddy, or a load balancer.
+- Table-focused tests for request parsing and HTTP handlers.
+
+## Run
+
+```powershell
+go run ./cmd/ipecho
+```
+
+The service listens on `:8080` by default.
+
+```powershell
+curl.exe http://localhost:8080/
+curl.exe http://localhost:8080/ip
+curl.exe http://localhost:8080/json
+curl.exe http://localhost:8080/headers
+curl.exe http://localhost:8080/user-agent
+```
+
+Use another port:
+
+```powershell
+$env:ADDR = ":9090"
+go run ./cmd/ipecho
+```
+
+Trust reverse proxy headers:
+
+```powershell
+$env:TRUST_PROXY_HEADERS = "true"
+$env:TRUSTED_PROXY_CIDRS = "127.0.0.1/32,::1/128"
+go run ./cmd/ipecho
+```
+
+Only enable `TRUST_PROXY_HEADERS` when your service is behind a proxy you control. Keep `TRUSTED_PROXY_CIDRS` limited to that proxy; otherwise, anyone can spoof forwarded IP headers.
+
+## Endpoints
+
+| Endpoint          | Response                                                   |
+|-------------------|------------------------------------------------------------|
+| `GET /`           | Browser dashboard or plain text client IP for CLI requests |
+| `GET /ip`         | Plain text client IP                                       |
+| `GET /json`       | JSON request metadata                                      |
+| `GET /headers`    | Plain text request headers                                 |
+| `GET /user-agent` | Plain text user agent                                      |
+| `GET /healthz`    | Plain text health check                                    |
+| `GET /favicon.ico` | Embedded favicon                                          |
+
+## Test
+
+```powershell
+go test ./...
+```
+
+## Production
+
+See:
+
+- [Production Guide](docs/production.md)
+- [nginx Configuration](docs/nginx.md)
+
+Regenerate icon assets and the Windows executable resource:
+
+```powershell
+go generate ./...
+```