Cookie и сессии: c.SetCookie, echo-contrib/session и CookieStore

Запрос «echo cookie» начинается там, где HTTP заканчивается. Протокол stateless: сервер обрабатывает каждый запрос как незнакомца — ни логина, ни истории, ни корзины. Кука — это договор о памяти: сервер в ответе выставляет заголовок Set-Cookie, браузер сохраняет его в своём хранилище и на каждом следующем запросе к этому сайту прикладывает заголовок Cookie с теми же парами имя=значение. Всё остальное — сессии, флеш-сообщения, remember-me — надстройки над этими двумя заголовками.

В echo работа с куками живёт в context.go, и контраст с формами из тринадцатого урока разительный: там был четвёртый метод и многоэтажный разбор multipart, здесь — три однострочника, после которых echo заканчивается и начинается net/http. Но тонкий слой обманчив: под ним сидят невалидные имена, которые молча не доходят до клиента, приоритеты истечения Expires против MaxAge и константы SameSite, из-за которых кука на localhost просто не вернётся. Мы пройдём весь стек честно: сначала сырые *http.Cookie и три метода контекста, затем echo-contrib/session — официальный мост к gorilla/sessions, чей интерфейс sessions.Store echo-contrib принимает как есть, не реализуя ничего своего. Сессия пользователя ляжет в Values, флеш-сообщения — под ключ _flash, подпись значений обеспечит securecookie с его HMAC. К концу урока POST /login на :1323 будет возвращать Set-Cookie с сессией, а GET /me — узнавать alice по имени.

Направление данных разное, и для него в net/http есть две разные структуры доступа. Исходящий путь: вы собираете &http.Cookie и зовёте http.SetCookie — она сериализует куку методом Cookie.String() и добавляет строку в заголовок ответа Set-Cookie. Входящий путь: браузер присылает заголовок Cookie в виде name1=value1; name2=value2 — и Request.Cookie(name) выцепляет одну куку по имени, а Request.Cookies() парсит их все. Док-комментарий у Cookies лаконичен: «Cookies parses and returns the HTTP cookies sent with the request» — парсинг живёт в readCookies, и echo сюда не добавляет ни строчки.

Одно направление — одна структура, и это важно понимать до кода. В ответе куку описывают атрибуты Path, Domain, Expires, MaxAge, Secure, HttpOnly, SameSite — они говорят браузеру, КОГДА и КУДА её отправлять; в запросе ни одного из этих атрибутов нет, клиент присылает только пары. Вручную запросы собирает Request.AddCookie — с оговоркой RFC 6265: «AddCookie does not attach more than one Cookie header field. That means all cookies, if any, are written into the same line, separated by semicolon» — все куки уезжают одной строкой через точку с запятой, второго заголовка Cookie не будет.

Echo не прячет ни одну из сторон: c.SetCookie добавляет Set-Cookie в ответ, c.Cookie и c.Cookies читают входящие. Каждый из трёх методов — чистое делегирование, и это не лень, а философия фреймворка: echo держится тонкой обёрткой, а вся политика — валидность имени, приоритет Max-Age над Expires, скоуп Path — остаётся в стандартной библиотеке, где её можно прочитать и проверить. Теперь к точным строкам context.go.

Времени у куки два механизма, и в Go они конкурируют. Expires — абсолютная дата; MaxAge — относительный счётчик в секундах, и его семантика закомментирована в структуре дословно: «MaxAge=0 means no 'Max-Age' attribute specified», «MaxAge<0 means delete cookie now, equivalently 'Max-Age: 0'», «MaxAge>0 means Max-Age attribute present and given in seconds». Ноль — не «удалить» и не «навсегда», а «атрибута нет»: кука станет сессионной и умрёт вместе с браузером. Если заполнить оба поля, Cookie.String() выпишет оба заголовка; gorilla не полагается на приоритеты браузеров — его NewCookie сам рассчитывает Expires из MaxAge «for Internet Explorer compatibility», но об этом после.

Три флага — про границы доверия. Secure запрещает браузеру отправлять куку по http; HttpOnly прячет её от document.cookie, снимая половину прибыли с кражи через XSS; SameSite решает, ехать ли куке в кросс-сайтовых запросах. В Go это константы типа http.SameSite — SameSiteDefaultMode SameSite = iota + 1, дальше Lax, Strict, None, — а их смысл сформулирован в доке стандартной библиотеки: «SameSite allows a server to define a cookie attribute making it impossible for the browser to send this cookie along with cross-site requests. The main goal is to mitigate the risk of cross-origin information leakage, and provide some protection against cross-site request forgery attacks».

Здесь мы останавливаемся сознательно: браузерная механика этих трёх флагов — почему None требует Secure, что именно Lax пропускает, а Strict нет, чем опасен document.cookie — уже разобрана в уроке fiber про cookie и сессии, и пересказывать её второй раз нечестно. Для echo важно другое: атрибуты вы ставите руками в каждом &http.Cookie, а в сессиях — один раз в Options хранилища, и от дефолтов этого Options вас будет отделять один сюрприз.

Кука с голым значением — это память без авторства. Три ограничения становятся заметны сразу. Первое: значение видит клиент — заголовок Set-Cookie читается глазами, а document.cookie и панель разработчика делают его общедоступным; любые «userId=7» — приглашение к подмене. Второе: объём — практический потолок куки около четырёх килобайт на пару имя-значение, и на большее не рассчитывайте. Третье: структура — в Value живёт строка, и каждую вложенную сущность надо сериализовать и защитить отдельно.

Сессия решает всё разом: данные лежат в карте Values — но на какой стороне, зависит от хранилища. В классической cookie-сессии данные не прячутся на сервер: они сериализуются, подписываются ключом (и опционально шифруются) и целиком уезжают в куку — сервер остаётся без состояния: подделать значение без ключа нельзя, а прочитать без шифрования можно. Запрос «сессии echo» выводит ровно на эту конструкцию: пакет github.com/labstack/echo-contrib/session — официальный мост echo к gorilla/sessions, стандарту де-факто с 2012 года. Совместимость с Gorilla здесь честная до типа: echo-contrib не реализовал своё хранилище — он принимает ЛЮБОЙ sessions.Store из gorilla и больше ничего не хранит. CookieStore, FilesystemStore, ваш собственный имплементатор трёх методов — всё это подходит без адаптеров.

Сравнение с курсом fiber из его двенадцатого урока уместно одной строкой: у fiber v3 собственная session-механика с адаптерами Storage, у echo — мост к зрелому gorilla; разные философии, одинаковый протокол Set-Cookie под ними. В gorilla/sessions Session — это struct с картой Values, а Store — интерфейс из трёх методов: Get, New, Save. Разберём обе стороны моста по исходникам.

Пакет gorilla/sessions держит три сущности. Session — рабочая единица: struct из четырёх экспортируемых полей — ID string, Values map[interface{}]interface{}, Options *Options и IsNew bool. Док-комментарий предупреждает заранее: ID — «generated by stores. It should not be used for user data» — это внутренний идентификатор, а не место для логина; всё ваше живёт в Values. Карта нетипизированная — ключ и значение любого типа — потому что сериализатор по умолчанию encoding/gob, который умеет почти всё, но требует gob.Register для нестандартных типов; пакет сам в init регистрирует []interface{}{}. IsNew — главный диагностический флаг: true значит, что куки не было или она не расшифровалась.

Store — интерфейс из трёх методов: Get должен вернуть кэшированную сессию, New — создать (и «should never return a nil session, even in the case of an error»), Save — сохранить. Разница между Get и New описана в доке дословно: «calling New() twice will decode the session data twice, while Get() registers and reuses the same decoded session after the first call». Реестром занимается Registry: он кладётся в контекст запроса и хранит map имя→сессия, поэтому повторный session.Get с тем же именем в пределах одного запроса бесплатен и возвращает тот же указатель. Тот же Registry — источник ошибки на невалидном имени: «sessions: invalid character in cookie name: %s» — gorilla проверяет имя куки раньше, чем net/http успеет что-то сказать.

Осталась механика конвейера: где Values превращаются в Set-Cookie и обратно. Это CookieStore — и тут же дефолтные Options, из-за которых локальный http-сервер молча теряет сессию.

CookieStore — хранилище, где вся сессия живёт в куке, а сервер только подписывает её. Конструктор описывает ключи так: «Keys are defined in pairs to allow key rotation, but the common case is to set a single authentication key and optionally an encryption key. The first key in a pair is used for authentication and the second for encryption. The encryption key can be set to nil or omitted in the last pair, but the authentication key is required in all pairs». Рекомендации по длинам тоже в доке: аутентификационному ключу — «32 or 64 bytes», ключу шифрования — «16, 24, or 32 bytes to select AES-128, AES-192, or AES-256». Из пар строится Codecs — срез securecookie.Codec через CodecsFromPairs: несколько пар — это ротация, старые куки декодируются старым ключом, новые кодируются первым.

Чтение: CookieStore.New достаёт куку из запроса и отдаёт её securecookie — if c, errCookie := r.Cookie(name); errCookie == nil { err = securecookie.DecodeMulti(name, c.Value, &session.Values, s.Codecs...) }; при успехе IsNew = false. Важный нюанс из доки Get: «It returns a new session and an error if the session exists but could not be decoded» — битая или подделанная кука НЕ превращается в панику и в пустоту: вы получаете новую сессию И ошибку, и решение «пустить ли гостя» остаётся вашим. Запись: Save кодирует карту — securecookie.EncodeMulti(session.Name(), session.Values, s.Codecs...) — и выставляет куку http.SetCookie(w, NewCookie(session.Name(), encoded, session.Options)).

Сроки: метод store.MaxAge(age) меняет Options.MaxAge и прогоняет то же число по всем кодекам, чтобы срок подписи совпадал со сроком куки; у отдельной сессии — свой Options.MaxAge, и -1 удаляет её немедленно: NewCookie при MaxAge<0 ставит «Expires = time.Unix(1, 0)» — «Set it to the past to expire now». Сам Options — подмножество полей куки, что заявлено в доке структуры: «Fields are a subset of http.Cookie fields» — те же Path, Domain, MaxAge, Secure, HttpOnly, SameSite плюс Partitioned из свежих стандартов. А вот дефолтный Options конструктора — ловушка, вынесенная в отдельный вопрос ниже. Серверная альтернатива — FilesystemStore: те же ключи и интерфейс, но сериализованная сессия лежит файлом на диске (каталог или os.TempDir), и в куке едет только идентификатор.

Флеш — это значение, которое должно показаться ровно один раз: «задача сохранена», «неверный пароль», «файл слишком большой». Механика gorilla помещается в два метода Session и одну константу: const flashesKey = "_flash" — дефолтный ключ, под которым флешы лежат в той же карте Values. AddFlash(value, vars...) дописывает значение в срез под ключом (свой ключ передаётся вторым аргументом: AddFlash("err", "notice")), а Flashes(vars...) возвращает срез И стирает его — комментарий в исходнике не оставляет вариантов: «Drop the flashes and return it», в коде — delete(s.Values, key).

Отсюда три правила, из которых растёт весь паттерн. Первое: прочёл — стёр; второй вызов Flashes в том же запросе вернёт пустой срез, потому что ключ уже удалён из Values. Второе: стирание живёт только в памяти запроса, пока не случился Save — именно поэтому в каноне после sess.Flashes() стоит sess.Save: иначе «прочитанный» флеш вернётся при следующем заходе и покажется второй раз. Третье: положил — в одном запросе, прочитал — в следующем: форма с ошибкой валидации из тринадцатого урока кладёт AddFlash("title обязателен") и редиректит обратно на страницу формы, а её обработчик при рендере вызывает Flashes и показывает сообщение один раз. Пакетная версия сохранения есть и на уровне пакета: sessions.Save(r, w) — в доке дословно «Save saves all sessions used during the current request» — прогоняет Registry.Save и собирает ошибки в MultiError — удобно, когда хендлер работал с несколькими именами сессий.

В fiber двенадцатого урока тот же паттерн собирался на родной сессии — считайте это вторым свидетелем: положил → редирект → прочитал → стёр — универсальный ритм одноразовых сообщений, различаются только API. Дальше — последняя деталь конвейера: чем именно подписана ваша Values, когда она превращается в строку куки.

Загадка кодирования решается в соседнем пакете gorilla/securecookie — том самом, чей Codec торчит из CookieStore.Codecs. Интерфейс двухметодный: Encode(name string, value interface{}) (string, error) и Decode(name, value string, dst interface{}) error. Конструктор — securecookie.New(hashKey, blockKey): первый ключ обязателен и «used to authenticate values using HMAC», второй опционален и включает шифрование AES (длина 16, 24 или 32 байта — AES-128/192/256). Дефолты: хеш-функция sha256.New, срок подписи 86400 * 30 секунд, потолок длины 4096 — «which is the maximum value accepted by Internet Explorer», сериализатор encoding/gob (JSONEncoder включается SetSerializer).

Конвейер Encode описан в доке целиком: «It serializes, optionally encrypts, signs with a message authentication code, and finally encodes the value». В коде подпись строится по строке «name|date|value» — имя куки участвует в MAC, поэтому кука одного имени не переиспользуется под другим. Результат — base64 от «date|value|mac». Decode идёт наоборот и на каждом шаге может отказать: ошибка «the value is not valid» (ErrMacInvalid) — подпись не совпала, причём сравнение делает subtle.ConstantTimeCompare, защита от тайминг-атак; «expired timestamp» — MAC верен, но дата за пределами maxAge; «timestamp is too new» — при настроенном MinAge. Имя при декодировании должно совпасть с именем при кодировании — проверяется тем же MAC.

И обязательная оговорка о ключах: «keys created using GenerateRandomKey() are not automatically persisted. New keys will be created when the application is restarted, and previously issued cookies will not be able to be decoded» — ключ, сгенерированный на старте, убивает все сессии при каждом деплое. Секрет хранят в окружении или файле, как любой другой конфиденциальный параметр. И не путайте это с Token.SignedString из мира JWT: там подписывается целый токен с клеймами и отдельной логикой проверки — пятнадцатый урок курса echo, JWT-аутентификация, встретит вас именно этим методом; securecookie подписывает значения кук, и у них у этого механизма иная математика и другой срок годности.

Канон научился помнить пользователя. Трио context.go — Cookie, SetCookie, Cookies — оказалось тремя однострочниками над net/http с одним честным сюрпризом: невалидное имя молча не доходит до клиента. Кука темы на /api/v1/theme показала литерал &http.Cookie с Max-Age в проводе; сессия на /login, /me, /logout — мост echo-contrib/session, за которым стоит gorilla/sessions без единой подмены: Config.Store — это sessions.Store, и никакого своего хранилища echo-contrib не содержит. Карта Values, Registry с кэшем на запрос, CookieStore с его ключевыми парами и дефолтными Options, флеш-сообщения под _flash со стиранием при чтении, подпись securecookie с HMAC по «name|date|value» — весь конвейер сверен с исходниками v4.15.0, v0.18.0, gorilla/sessions v1.4.0 и securecookie v1.1.2.

Про песочницу честно, как во всём курсе: у курса Echo её нет — код исполняется локально, поэтому runner-ов здесь не будет; соберите канон go run main.go и прогоните цепочку curl: POST /login с JSON alice/qwerty-42, взгляд на Set-Cookie, затем GET /me с -b "user=..." — и тот же запрос без куки, чтобы увидеть is_new: true. Отдельно сломайте подпись: измените один символ значения куки user и убедитесь, что /me отдаёт новую сессию, а не ошибку — и объясните, почему это ровно та логика, которая написана в CookieStore.New.

Следующий, пятнадцатый урок курса echo — JWT-аутентификация: echo-jwt middleware, клеймы, роли, refresh-токены. Сессия держит состояние в куке и в карте Values; JWT несёт состояние в самом токене, подписанном SignedString, — и первые вопросы там будут про то, где такой токен хранить и что он, в отличие от подписанной куки, прочитать умеет. Навигация по курсу — на странице курса Echo; форма, чьи ошибки заслуживают флеша, — в уроке про формы и файлы; параллельная реализация той же темы в fiber — в уроке fiber про cookie и сессии — там своя session-механика v3, пригодится для сравнения подходов, но не как источник фактов об echo.