woggioni-opencode-agent
bba22b357e
- bump kaya-core/kaya-rsgi to >= 0.0.3 and add kaya-forwarded: forwarded header handling is no longer built into core, it is opt-in via ForwardedHeadersMixin and gated on trusted proxy CIDRs - add TRUSTED_PROXY_CIDRS setting (comma-separated CIDRs, validated at startup; empty means no proxy is trusted) and wire the mixin in app.py - cover trusted/untrusted peers, all-trusted chains and the RFC 7239 Forwarded header with port in the test suite - document the new variable in README, .env.example and docker-compose.yml
128 lines
4.8 KiB
Markdown
128 lines
4.8 KiB
Markdown
# 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.
|
|
|
|
## 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
|
|
```
|
|
|
|
### 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
|
|
|
|
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`.
|