149 lines
4.5 KiB
Markdown
149 lines
4.5 KiB
Markdown
# WebRobo API
|
|
|
|
Browser automation API with built-in anti-bot stealth. Send a URL and a sequence of declarative actions — fill a field,
|
|
click, wait for an element — and get back the rendered page, including sites behind Cloudflare-style JS challenges.
|
|
|
|
## Status
|
|
|
|
Early MVP (v0), under active development. Single browser engine, no queue, no billing yet — see [Roadmap](#roadmap).
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Client → Caddy (TLS) → FastAPI → API-key auth → semaphore acquire
|
|
│
|
|
▼
|
|
Camoufox browser context
|
|
(run actions, collect result)
|
|
│
|
|
▼
|
|
release semaphore → response
|
|
```
|
|
|
|
- **Engine**: [Camoufox](https://camoufox.com/) (stealth Firefox, driven via Playwright). Chosen for v1 because
|
|
Firefox-based fingerprinting is less commoditized against anti-bot vendors than patched Chromium.
|
|
- **API**: FastAPI, single versioned endpoint (`POST /v1/solve`).
|
|
- **Concurrency**: bounded by an `asyncio.Semaphore` over browser contexts — no external job queue in v1. Simpler to
|
|
run, hard ceiling on throughput per instance (see Roadmap for scaling out).
|
|
- **Auth**: per-client API key (`X-API-Key` header), checked against a SQLite table. (SQLAlchemy ORM)
|
|
- **Logging**: every request's outcome (success/failure/duration) is persisted — this becomes the success-rate data used
|
|
to evaluate the service and talk to clients about reliability.
|
|
- **Proxies**: not managed by the service in v1 — the client supplies their own proxy per request if they need one.
|
|
- **Deployment**: single Docker container behind a Caddy reverse proxy.
|
|
- **Canvas fingerprint** по дизайну генерируется каждую сессию новый.
|
|
|
|
### Planned project layout
|
|
|
|
```
|
|
src/
|
|
main.py # FastAPI app + router wiring
|
|
config.py # settings (env vars)
|
|
api/
|
|
solve.py # POST /v1/solve
|
|
deps.py # API-key auth dependency
|
|
engine/
|
|
browser.py # Camoufox context pool + semaphore
|
|
actions.py # fill / click / wait_for execution
|
|
schemas.py # SolveRequest / SolveResponse / Action models
|
|
db/
|
|
models.py # api_keys, request_logs
|
|
session.py
|
|
tests/
|
|
wheels/ # whl библиотеки для оффлайн установки под Ubuntu Noble
|
|
Dockerfile
|
|
requirements.txt
|
|
env.example
|
|
```
|
|
|
|
## API (draft)
|
|
|
|
```
|
|
POST /v1/solve
|
|
X-API-Key: <key>
|
|
|
|
{
|
|
"captcha": "token",
|
|
"url": "https://example.com/login",
|
|
"actions": [
|
|
{"type": "fill", "selector": "#email", "value": "user@example.com"},
|
|
{"type": "fill", "selector": "#password", "value": "..."},
|
|
{"type": "mouse_move", "selector": "#submit"},
|
|
{"type": "click", "selector": "#submit"},
|
|
{"type": "wait_for", "selector": ".dashboard", "timeout": 30}
|
|
],
|
|
"proxy": "socks5://user:pass@host:port",
|
|
|
|
"screen": "1280x920",
|
|
"user_agent": "Firefox",
|
|
"timeout": 120
|
|
}
|
|
```
|
|
|
|
Response:
|
|
|
|
```json
|
|
{
|
|
"ok": false,
|
|
"context": "000000",
|
|
"error": "action_error",
|
|
"html": "<html>...</html>",
|
|
"cookies": [
|
|
{
|
|
"name": "session",
|
|
"value": "..."
|
|
}
|
|
],
|
|
"actions_result": [
|
|
{
|
|
"type": "fill",
|
|
"ok": true
|
|
},
|
|
{
|
|
"type": "fill",
|
|
"ok": true
|
|
},
|
|
{
|
|
"type": "click",
|
|
"ok": true
|
|
},
|
|
{
|
|
"type": "wait_for",
|
|
"ok": false,
|
|
"error": "Element not located"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
On failure, `status` is `"error"` and `error` carries a machine-readable reason (`selector_not_found`, `timeout`,
|
|
`navigation_failed`, ...).
|
|
|
|
Fill команда включает 3 действия
|
|
|
|
1. `{"type": "mouse_move", "selector": "#email"},` - навести мышку на элемент
|
|
2. `{"type": "click"},` - клик в текущие координаты
|
|
3. `{"type": "typing", "value": "user@example.com"},` - набор текста
|
|
|
|
## Roadmap
|
|
|
|
Deliberately out of scope for v1:
|
|
|
|
- Job queue (Redis/RabbitMQ) + multiple worker VPS for horizontal scaling
|
|
- Real billing/usage plans beyond a flat API-key check
|
|
- Broader action vocabulary beyond fill/click/wait_for
|
|
- Second engine (Patchright/Chromium) for targets where the Firefox fingerprint doesn't fit
|
|
|
|
## Local development
|
|
|
|
```bash
|
|
python -m venv .venv
|
|
source .venv/bin/activate
|
|
make sync-offline
|
|
uvicorn app.main:app --reload
|
|
```
|
|
|
|
## TODO:
|
|
|
|
-[ ] добавить пакет обертку для python
|
|
-[ ]
|