pyfconfig/README.md

# pyfconfig

A clone of [ifconfig.me](https://ifconfig.me/) built on the
[kaya](https://gitea.woggioni.net/woggioni/kaya) framework
(`kaya-core` + `kaya-rsgi`), served by [Granian](https://github.com/emmett-framework/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.

A second image runs the exact same app on [GraalPy](https://www.graalvm.org/python/)
(GraalVM Community Edition 25) instead of CPython — see
[Dockerfile.graalpy](Dockerfile.graalpy) and the
[GraalPy image](#graalpy-image) section. Because GraalPy is not ABI-compatible
with CPython wheels, the compiled `granian` and `rloop` extensions are built
from source against GraalPy during the image build.

## 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](#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:

```console
$ 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)

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

### GraalPy image

An equivalent image based on `ghcr.io/graalvm/graalpy-community:25`
(GraalPy 25.0.2 / Python 3.12.8) is available via a separate compose file:

```bash
docker compose -f docker-compose.graalpy.yml up -d --build
# App published at http://localhost:8080
```

This image is published to the registry as the `*-graalpy` tags
(e.g. `latest-graalpy`, `0.1.0-graalpy`).

### On the host

```bash
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](https://github.com/gi0baro/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

```bash
. .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

Two images are built from this repository:

- `Dockerfile` — multi-stage alpine build on CPython, producing a minimal,
  non-root runtime image.
- `Dockerfile.graalpy` — multi-stage Oracle Linux build on GraalPy 25, where
  the compiled `granian` and `rloop` extensions are compiled from source
  against GraalPy (the Rust toolchain stays in the builder stage).

Pushing a `release/*` tag triggers the Gitea Actions workflow in
`.gitea/workflows/build.yaml`, which builds and publishes both images to
`gitea.woggioni.net/woggioni/pyfconfig`: the CPython image as `latest` /
`<version>`, and the GraalPy image as `latest-graalpy` / `<version>-graalpy`.