# AGENTS.md

## 🎯 Цель проекта

Разработка локального HTTP/HTTPS прокси-сервера на Windows, который:

* использует системные proxy-настройки (включая PAC/WPAD)
* поднимает локальный proxy (127.0.0.1:PORT)
* требует Basic-аутентификацию
* проксирует весь трафик через системный proxy (upstream)
* работает в оффлайн/ограниченной среде

---

## 🧱 Текущий стек

* Язык: C#
* Платформа: .NET 6+
* ОС: Windows
* Используемые API:

  * WinHTTP (`WinHttpGetProxyForUrl`)
  * TcpListener / TcpClient
  * низкоуровневый HTTP parsing

---

## ✅ Уже реализовано

* Локальный proxy сервер (TCP)
* Поддержка HTTP
* Поддержка HTTPS через CONNECT (туннель)
* Basic Proxy Authentication
* Чтение системного proxy через WinHTTP
* Поддержка PAC/WPAD (через WinHttpGetProxyForUrl)
* Проксирование через upstream proxy
* Двунаправленный стриминг (Pump)

---

## ⚠️ Известные проблемы / ограничения

### ❗ 1. Упрощённый HTTP parser

* читает только первый пакет (8192 байт)
* не обрабатывает:

  * chunked encoding (входящий)
  * большие POST body
  * keep-alive корректно

---

### ❗ 2. Нет полноценной обработки proxy auth upstream

* если upstream требует:

  * NTLM / Kerberos → частично работает через WinHTTP
  * Basic → не всегда прокидывается

---

### ❗ 3. Нет connection pooling

* каждое соединение → новый TcpClient

---

### ❗ 4. Нет логирования

* сложно дебажить поведение

---

### ❗ 5. Нет таймаутов / retry

* возможны зависания

---

## 🔧 Следующие задачи (приоритет)

### 🔥 HIGH

* [ ] Полный HTTP parser (или перейти на HttpListener/Kestrel)
* [ ] Корректная работа с большими body (streaming request)
* [ ] Обработка chunked encoding
* [ ] Таймауты на сокеты

---

### ⚙️ MEDIUM

* [ ] Логирование (запросы, ошибки)
* [ ] Ограничение количества соединений
* [ ] Graceful shutdown

---

### 🚀 ADVANCED

* [ ] Connection pooling
* [ ] Кеширование CONNECT туннелей
* [ ] Поддержка SOCKS5
* [ ] MITM HTTPS (с генерацией сертификатов)

---

## 🧪 Как тестировать

### curl

curl -x http://user:pass@127.0.0.1:8888 http://example.com

### HTTPS

curl -x http://user:pass@127.0.0.1:8888 https://example.com -k

---

## 🐛 Типичные ошибки

### "vite not executable"

→ проблема несовместимости node_modules (macOS → Windows)

### "Proxy 407"

→ не передан Proxy-Authorization

### "502 Bad Gateway"

→ upstream proxy не принял CONNECT

### timeout

→ проблема с PAC / WinHTTP / сетью

---

## 🧠 Важные знания

* node_modules нельзя переносить между ОС
* WinHTTP ≠ WinINET (разные API)
* PAC требует WinHttpGetProxyForUrl
* CONNECT = raw TCP tunnel
* Proxy chaining ломается без правильного handshake

---

## 📌 Контекст пользователя

* Работает в оффлайн/ограниченной сети
* Нужен полный контроль над proxy
* Использует Windows
* Требуется системная интеграция proxy

---

## 📎 Дальнейшее развитие

Если продолжать:

* перейти на async socket server с IOCP
* добавить полноценный HTTP stack
* или встроить готовый proxy engine (YARP / Kestrel)

---

## 💬 Примечание

Это инженерный прототип прокси.
Не production-ready, но уже близко к рабочему инструменту.

Любые дальнейшие доработки — ориентироваться на реальные ошибки в сети.