gorilla/websocket: установка и Upgrader

Типичный сценарий: у вас уже есть сервис на net/http или на роутере — страницы отдаются, API живёт, и вдруг появляется задача с real-time: чат, уведомления, живой счётчик. Тащить фреймворк ради одной функции не хочется, и хорошо, что не нужно: WebSocket на Go — это одна библиотека поверх того, что уже есть. gorilla/websocket приносит три главных сущности: Upgrader, который проводит рукопожатие, Conn — само соединение, и Dialer — исходящее соединение для тестов и сервер-сервер трафика. Библиотека собрана на чистой стандартной библиотеке: в go.mod проекта появляется ровно одна запись, транзитивных зависимостей нет, а хендлеры остаются обычными http.HandlerFunc. Иными словами, WS-сервер — это всё ещё ваш старый сервер: те же маршруты, тот же ListenAndServe, просто один из хендлеров после апгрейда перестаёт говорить по HTTP. Разберём путь целиком — от go mod init до полей Upgrader, которыми решается, кого впускать.

Начните с чистой папки и модуля. go mod init example.com/ws101 объявляет модуль — без этого go get некуда записывать зависимость; имя модуля — это путь, а не URL, и его не нужно заводить в репозитории. Затем go get github.com/gorilla/websocket подтягивает актуальную версию первой мажорной ветки и пишет её в require go.mod — на момент курса это v1.5.x. Суффиксов в пути импорта нет и не будет: у chi пятая мажорная живёт прямо в пути как /v5, у gorilla путь короткий — github.com/gorilla/websocket, и это частый источник опечаток в туториалах в обратную сторону. В коде пакет импортируется одним именем — websocket — и дальше вы пишете websocket.Upgrader, websocket.Conn, websocket.TextMessage. go.sum получит хэши для воспроизводимой сборки, как у любой зависимости; go mod tidy вычистит лишнее, если вы удалили код. Три команды и одна строка импорта — вся церемония установки.

Первая же попытка поставить библиотеку регулярно спотыкается на двух граблях, и обе лечатся пониманием, а не переустановкой. Грабля первая: go get запущен в папке без go mod init — инструмент честно отвечает, что go.mod не найден, и ничего не ставит. Модуль — не формальность, а адрес, куда пишется зависимость, поэтому три команды из блока выше выполняются строго в этом порядке. Грабля вторая — копипаст импортов из соседних туториалов: путь с /v5 из урока по chi не скомпилируется с gorilla, и наоборот — короткий путь без версии здесь не ошибка, а норма. Отдельная история — старые статьи: API gorilla стабилен, но примеры эпохи до 2018 года иногда тянут давно удалённые подпакеты. Если сборка ругается на неожиданный путь, сверяйтесь не с памятью, а с go.mod: что записано в require — то и импортируется. И приучите себя к go mod tidy после экспериментов: он убирает зависимости от удалённого кода и не даёт go.mod превратиться в свалку.

Upgrader — конфигурация рукопожатия, и его поля стоит знать до того, как писать код. ReadBufferSize и WriteBufferSize задают размеры внутренних буферов ввода-вывода на соединение; ноль означает дефолт в 4096 байт. HandshakeTimeout — дедлайн на фазу рукопожатия: клиент, приславший GET и замолчавший, не будет держать соединение вечно. CheckOrigin — функция-фильтр, решающая, чужой ли Origin пришёл; дефолт строгий, о нём отдельно ниже. Subprotocols выбирает субпротокол из заголовка Sec-WebSocket-Protocol, EnableCompression включает расширение permessage-deflate для сжатия кадров, а Error позволяет заменить стандартный способ записи HTTP-ошибки при провале апгрейда на свой — например, чтобы логировать причину. Сам апгрейд делает метод Upgrade(w http.ResponseWriter, r *http.Request, responseHeader http.Header): третий аргумент — заголовки, которые хочется добавить в ответ 101 до его отправки, скажем cookie; чаще всего передают nil. Возвращает метод conn — соединение — и ошибку, и обращение с ошибкой здесь нестандартное.

Браузер всегда прикладывает к рукопожатию Origin — адрес страницы, открывшей соединение. У WebSocket нет CORS в HTTP-смысле; вместо него — CheckOrigin. Дефолт gorilla строгий: Origin должен совпасть с Host самого запроса, иначе рукопожатие отклоняется с 403. Логика простая: страница чужого сайта не должна открывать сокет к вашему сервису и читать сообщения от имени залогиненного пользователя — cookies-то браузер приложит автоматически. В реальной разработке дефолт напомнит о себе сразу: фронтенд на localhost:3000, сервер на localhost:8080 — и рукопожатие отвергнуто, нужен свой CheckOrigin, пропускающий локальные адреса. Опасность в другом: в интернете полно советов написать return true и жить дальше. На dev это терпимо, в проде — открытая дверь для чужих страниц: отдельный урок курса про origins разбирает атаку и правильные фильтры, а здесь запомните форму: CheckOrigin — функция из http.Request в bool.

На каждое соединение gorilla выделяет два буфера — на чтение и на запись — размеров ровно из Upgrader, по умолчанию по 4096 байт каждый. От размера зависит баланс: крупный буфер режет число системных вызовов на больших сообщениях и ускоряет ввод-вывод, но множит память — буферы живут у каждого соединения, пока оно открыто. Грубая прикидка с условием: десять тысяч открытых клиентов при паре буферов по 4096 байт — это порядка восьмидесяти мегабайт только на буферы; при 1024 — десять. Для чата и уведомлений, где сообщения короткие, значения 1024-4096 закрывают потребности; для передачи крупных бинарных кусков крупнее буфер оправдан. Писать в этих буферах вручную не придётся: ReadMessage и WriteMessage из четвёртого урока прячут всю механику. Знать поля стоит по другой причине: при отладке памяти под нагрузкой первые два подозреваемых — размеры буферов Upgrader и количество живых соединений.

Частая постановка: сервис с REST уже живёт за nginx, и в него добавляют /ws. На локалке всё работает, а в проде соединение умирает через минуту тишины — классика с тремя причинами. Первая: nginx по умолчанию не прокидывает заголовки апгрейда, и рукопожатие даже не начинается; лечится блоком location /ws с proxy_set_header для Upgrade и Connection плюс proxy_http_version 1.1. Вторая: proxy_read_timeout по умолчанию — шестьдесят секунд, и молчаливое WS-соединение прокси рвёт, хотя оба конца живы; значение поднимают, а правильнее — вешают ping-механизм из шестого урока, чтобы кадры ходили чаще таймаута. Третья: gzip-слой или обёртка ResponseWriter в цепочке приложения ломает Hijack — об этом была врезка выше. Полезно понять общий принцип: для WS-маршрута весь путь от браузера до Go-процесса должен быть прозрачным для апгрейда, и каждый прокси в цепочке проверяется отдельно. Этот чек-лист я прогоняю перед любым демо real-time: девять из десяти жалоб «сервер падает» оказываются прокси.

Для полноты картины — как то же рукопожатие выглядит в альтернативной библиотеке. Пакет coder/websocket не имеет Upgrader: функцией Accept(w, r) вы принимаете соединение и сразу получаете conn, жизнью соединения управляет контекст запроса, а чтение построено на io.Reader вместо ReadMessage — сообщение приходит потоком, который вы читаете сами. Концептуально всё то же самое: тот же HTTP-запрос, тот же ответ 101, то же требование одной горутины-писателя на соединение. Меняется стиль: gorilla держит состояние в структуре Conn с полями-дедлайнами, coder — в контекстах и ридерах, что ближе к современному Go, но непривычнее после учебников. Мой практический критерий не меняется от направления: если в проекте уже есть код на gorilla или команда его знает — переезд не оправдан, API учится за вечер; для нового сервиса в ctx-first стиле честнее coder. Остальной курс идёт на gorilla — по нему написано больше всего, а навык переносится на любую из библиотек.