SOCKS5 — API

Entry points

start.php определяет SOCKS constants, подключает config и HandshakeBuffer, создаёт worker и callbacks. config.php читает окружение и формирует $config; прямое исполнение config отдельно от constants не является способом запуска сервиса.

HandshakeBuffer.php не создаёт listener и не выполняет сетевые операции.

HandshakeBuffer

Метод	Контракт
append(string $data): void	Добавить байты; при суммарном размере больше 65 536 — UnexpectedValueException.
take(int $stage): ?string	Извлечь один целый packet; null, если пока не хватает данных или стадия не обслуживается parser.
drain(): string	Отдать остаток и очистить буфер.

Стадии: 0 — greeting, 1 — username/password, 2 — destination request. Извлечение убирает только готовый packet, оставляя следующие данные.

Greeting требует версию 5 и хотя бы один метод. Auth subnegotiation требует версию 1 и непустые поля. Destination требует версию 5, reserved byte 0, распознаваемый address type и корректное непустое hostname для соответствующей формы.

IPv6 packet может быть собран parser, но handler затем отклоняет IPv6 destination. Успешный разбор длины не означает поддержку relay-команды.

Формы пакетов

greeting:  VER | NMETHODS | METHODS
user/pass: VER=1 | ULEN | USER | PLEN | PASS
connect:   VER=5 | CMD | RSV=0 | ATYP | DST.ADDR | DST.PORT

Порт — двухбайтовое число в network byte order. В успешном CONNECT reply адрес и порт берутся из локального конца установленного upstream-соединения, а не всегда задаются нулями.

Отказы

Неподдерживаемый метод greeting возвращает 05 ff; неправильный password — auth reply с ненулевым status. Ошибка upstream приводит к failure reply и закрытию; отсутствие DNS A-адреса — к host error. Отключённый UDP-запрос получает command-not-supported.

Некорректная структура, превышение буфера и handshake timeout могут закрыть соединение без полного SOCKS error reply. Клиент должен обрабатывать EOF.

При ошибке подключения проверьте listener/port, credentials и IPv4/A-record destination. Лог выбирается через SOCKS5_LOG_FILE; не помещайте его в публичный web-root.

Локальная интеграционная проверка

python3 tests/integration.py в исходном репозитории поднимает loopback echo-upstream и прокси на временном порту с временными PID/log paths. Проверяются разбиение handshake, объединённые auth/CONNECT/ранний payload, отказ no-auth, неверный password, отключённый UDP и неверный greeting.

Проверка не меняет production listener и не подтверждает поддержку IPv6, UDP или TLS на участке клиент–прокси. Для этих контрактов нужна соответствующая реализация, а не включение несуществующей env-опции.