pyfconfig/README.md

pyfconfig

A clone of ifconfig.me built on the kaya framework (kaya-core + kaya-rsgi), served by Granian over the RSGI protocol.

Stack

• kaya-core — routing and HTTP request/response handling
• kaya-rsgi — Granian (RSGI) adapter
• kaya-forwarded — trusted-proxy handling of Forwarded / X-Forwarded-* headers
• granian — application server
• rloop — Rust event loop used by Granian instead of the stdlib asyncio loop
• httpx + pwo — test client over kaya's ASGI transport

No database, sessions, or authentication — the app is stateless.

Endpoints

Method	Path	Response
GET	/	HTML page for browsers (Accept: text/html), plain-text IP otherwise
GET	/ip	Client IP address
GET	/ua	User-Agent header
GET	/lang	Accept-Language header
GET	/encoding	Accept-Encoding header
GET	/mime	Accept header
GET	/charset	Accept-Charset header
GET	/forwarded	X-Forwarded-For header
GET	/all	All connection fields as key: value lines (empty fields included; remote_host shown as unavailable)
GET	/all.json	Same fields as a JSON object, empty fields omitted
GET	/api/health	Liveness probe ({"status":"ok"})

The /all field order mirrors the reference site: ip_addr, remote_host, user_agent, port, language, referer, connection, keep_alive, method, encoding, mime, charset, via, forwarded.

The reported client IP/port honor the Forwarded, X-Forwarded-For, X-Forwarded-Host and X-Forwarded-Port proxy headers only when the direct peer belongs to one of the TRUSTED_PROXY_CIDRS (see Configuration); the header chain is walked right-to-left skipping trusted proxies, so spoofed entries prepended by the client are never selected. Without trusted proxies configured, or when the peer is untrusted, the socket peer address is used.

Example:

$ curl http://localhost:8080/
203.0.113.7
$ curl http://localhost:8080/all.json
{"ip_addr":"203.0.113.7","user_agent":"curl/8.21.0","port":"51342","method":"GET","mime":"*/*"}

Running

With Docker Compose (recommended)

docker compose up -d --build
# App published at http://localhost:8080

On the host

cp .env.example .env   # optional; all settings have defaults
python -m venv .venv && . .venv/bin/activate
pip install --index-url https://gitea.woggioni.net/api/packages/woggioni/pypi/simple \
            --extra-index-url https://pypi.org/simple \
            -e .
granian --interface rsgi --loop rloop --host 0.0.0.0 --port 8000 pyfconfig.app:app

The --loop rloop flag (or GRANIAN_LOOP=rloop, already set in the Docker image) makes Granian run the app on the rloop Rust event loop instead of the stdlib asyncio loop.

Configuration

Environment variables (see .env.example):

Variable	Default	Description
SITE_NAME	pyfconfig	Public name used in the HTML page title and the curl examples (set to your domain, e.g. ifconfig.example.com)
TRUSTED_PROXY_CIDRS	(empty)	Comma-separated CIDRs/IPs of trusted reverse proxies (e.g. 127.0.0.1,10.0.0.0/8). Forwarded headers are honored only from these peers; empty means no proxy is trusted

The bind address is configured through Granian itself (GRANIAN_HOST / GRANIAN_PORT env vars or --host / --port CLI flags).

Tests

. .venv/bin/activate
python -m unittest discover -s tests -t .

The tests drive the app in-process through kaya's ASGI interface using httpx.ASGITransport; no external services are needed.

Project layout

src/pyfconfig/
├── app.py              # KayaApp assembly; imports route modules
├── config.py           # env-driven Settings dataclass
├── page.py             # HTML landing page builder (kaya has no templating)
└── routes/
    ├── health.py       # GET /api/health
    ├── root.py         # GET / with content negotiation
    └── connection.py   # /ip /ua /lang /encoding /mime /charset /forwarded /all /all.json
tests/
└── test_routes.py      # unittest + httpx.ASGITransport

Route modules import the module-level app from pyfconfig.app and register handlers with @app.GET(...) decorators at import time — pyfconfig.app imports them last to complete the wiring.

Deployment

The Dockerfile is a multi-stage alpine build producing a minimal, non-root runtime image; pushing a release/* tag triggers the Gitea Actions workflow in .gitea/workflows/build.yaml, which builds and publishes the image to gitea.woggioni.net/woggioni-opencode-agent/pyfconfig.