chore: init

2026-09-08 16:10:23 +04:00
commit 85b28835d1
@@ -0,0 +1,137 @@
+# 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.
+
+### Planned project layout
+
+```
+src/
+  main.py            # FastAPI app + router wiring
+  api/
+    solve.py         # POST /v1/solve
+    deps.py          # API-key auth dependency
+  core/
+    config.py        # settings (env vars)
+  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": "click", "selector": "#submit"},
+		{"type": "wait_for", "selector": ".dashboard", "timeout_ms": 30000}
+	],
+	"proxy": "http://user:pass@host:port",
+	"timeout_ms": 120000
+}
+```
+
+Response:
+
+```json
+{
+	"status": "ok",
+	"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": true
+		}
+	],
+	"error": null
+}
+```
+
+On failure, `status` is `"error"` and `error` carries a machine-readable reason (`selector_not_found`, `timeout`,
+`navigation_failed`, ...).
+
+Fill команда включает 3 действия
+
+1. `{"type": "locate", "selector": "#email"},` - навести мышку на элемент
+2. `{"type": "click"},` - клик в текущие координаты
+3. `{"type": "typing", "value": "user@example.com"},` - набор текста
+
+## Roadmap
+
+Deliberately out of scope for v1:
+
+- Second engine (Patchright/Chromium) for targets where the Firefox fingerprint doesn't fit
+- 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
+
+## Local development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+uvicorn app.main:app --reload
+```