111 lines
3.7 KiB
Markdown
111 lines
3.7 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
|
|
- **granian** — application server
|
|
- **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`.
|
|
|
|
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 --host 0.0.0.0 --port 8000 pyfconfig.app:app
|
|
```
|
|
|
|
### Configuration
|
|
|
|
Environment variables (see `.env.example`):
|
|
|
|
| Variable | Default | Description |
|
|
|---|---|---|
|
|
| `APP_HOST` | `0.0.0.0` | Bind host (informational; granian is configured via `GRANIAN_*`) |
|
|
| `APP_PORT` | `8000` | Bind port (informational) |
|
|
| `SITE_NAME` | `pyfconfig` | Public name used in the HTML page title and the curl examples (set to your domain, e.g. `ifconfig.example.com`) |
|
|
|
|
## 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`.
|