Запрос

POST /api/v1/orders?dry=1 HTTP/1.1     <- стартовая строка: метод, target, версия
Host: api.example.com                  <- обязателен в 1.1, иначе 400
Content-Type: application/json
Content-Length: 21
Authorization: Bearer eyJhbGciOi...
X-Request-Id: 0f1c-88ad-...
                                       <- ПУСТАЯ строка = конец заголовков
{"sku":"A-1","qty":2}

Строки разделяются строго \r\n (CRLF), а не \n. Регистр имён заголовков не важен (content-type == Content-Type), и в Go http.Header приводит имя к канонической форме (X-Request-Id). Это аукнется, если лезешь руками в map[string][]string: ключ "x-request-id" там не найдётся, нужен Header.Get.

Ответ

HTTP/1.1 201 Created                   <- версия, код, reason phrase (в HTTP/2 её нет вообще)
Content-Type: application/json; charset=utf-8
Location: /api/v1/orders/42
Transfer-Encoding: chunked

18
{"id":42,"status":"new"}
0
                                       <- нулевой чанк = конец тела

Где кончается тело - три варианта

• Content-Length: N велит прочитать ровно N байт. Длину надо знать заранее, то есть сначала собрать весь ответ.
• Transfer-Encoding: chunked режет тело на куски «длина в hex, CRLF, данные», а конец отмечает чанк нулевой длины. Нужен для стриминга, когда длина неизвестна: логи, SSE, выгрузка большой таблицы. В Go включается сам, если ты не поставил Content-Length и данных больше буфера.
• Закрытие соединения - легаси из HTTP/1.0: тело кончается там, где кончился TCP. Несовместимо с keep-alive.

Чем добить

В HTTP/2 стартовой строки нет: метод, схема, авторитет и путь стали псевдозаголовками :method, :scheme, :authority, :path, а у ответа есть :status. Reason phrase («Not Found» после 404) выбросили за ненадобностью. Имена заголовков в HTTP/2 пишутся только в нижнем регистре, прописная буква считается протокольной ошибкой.

Почему PUT идемпотентен, а POST нет

PUT /orders/42 означает «пусть по этому адресу лежит вот такое представление». Повтори хоть десять раз, состояние останется тем же. POST /orders означает «обработай вот эти данные», и адрес сервер выбирает сам, поэтому десять повторов дают десять заказов. Вот почему клиенты и прокси вправе автоматически ретраить GET/PUT/DELETE при сетевой ошибке, а POST нет.

Как сделать POST идемпотентным на практике

Через ключ идемпотентности: клиент генерирует UUID и шлёт его в заголовке Idempotency-Key. Сервер в транзакции пытается вставить этот ключ в таблицу с уникальным индексом. Если вставка прошла, он выполняет операцию и сохраняет рядом результат; если ключ уже есть, возвращает сохранённый ответ и ничего не выполняет. Так делают Stripe, YooKassa и все платёжные API. Ключ живёт с TTL (сутки-неделя). Тонкое место: состояние «ключ вставлен, но операция ещё выполняется». Второй запрос в этот момент должен получить 409 или подождать, а не начать вторую операцию.

2xx

• 200 OK - успех с телом.
• 201 Created: ресурс создан, обычно с заголовком Location на его адрес.
• 202 Accepted: приняли в обработку, результата ещё нет. Правильный код для асинхронных операций, к нему отдаём Location на статус-ресурс.
• 204 No Content - успех без тела (удаление, PUT без возврата). Тело писать нельзя вообще.
• 206 Partial Content отвечает на Range: докачка и стриминг видео.

3xx

• 301 Moved Permanently переносит навсегда, браузеры кэшируют его агрессивно и надолго. Ошибёшься - пользователи месяцами будут ходить на старый адрес, пока не почистят кэш.
• 302 Found / 307 Temporary Redirect переносят временно. Разница в том, что при 301/302 браузеры исторически меняли POST на GET, а 307 и 308 обязаны сохранять метод и тело. Нужен предсказуемый редирект - бери 307/308.
• Go 1.26 переехал на 307 в стандартном роутере. Раньше, когда net/http.ServeMux сам перекидывал /x на зарегистрированный /x/, он отдавал 301. Это была мина: 301 браузер кэширует практически навсегда, и после переделки роутов пользователь всё равно шёл по старому адресу, пока не почистит кэш, а POST по дороге превращался в GET. С Go 1.26 здесь уходит 307: он не кэшируется и сохраняет метод с телом. Хорошая иллюстрация того, почему «навсегда» в вебе стоит дороже всего.
• 303 See Other говорит «сходи туда методом GET»: канонический ответ на POST по паттерну Post/Redirect/Get, чтобы F5 не отправил форму дважды.
• 304 Not Modified - ответ на условный запрос: тела нет, бери из кэша.

4xx - где ошибаются чаще всего

• 400 Bad Request - запрос синтаксически сломан: не распарсился JSON, не тот тип поля.
• 401 Unauthorized на самом деле значит «не аутентифицирован»: токена нет, он протух или подпись не сошлась. Обязан идти с WWW-Authenticate. Клиенту есть смысл обновить токен и повторить.
• 403 Forbidden: «кто ты, понятно, но тебе нельзя». Повтор с тем же токеном бессмыслен. Путаница 401/403 остаётся самым частым ляпом в API.
• 404 Not Found: ресурса нет. Иногда его намеренно отдают вместо 403, чтобы не подтверждать чужому пользователю, что объект существует.
• 405 Method Not Allowed - путь есть, метод не тот; обязателен Allow.
• 409 Conflict означает конфликт с текущим состоянием: оптимистическая блокировка не сошлась, дубликат по уникальному ключу, попытка повторно оплатить оплаченный заказ.
• 412 Precondition Failed приходит, когда не выполнилось условие If-Match: ресурс изменили между чтением и записью.
• 422 Unprocessable Content: JSON валидный и разобрался, но бизнес-валидация не прошла («qty должен быть больше нуля»). Разница с 400: синтаксис против семантики. Это соглашение, а не жёсткое требование, но команды его любят.
• 429 Too Many Requests - рейт-лимит. Отдавай его с Retry-After, иначе клиенты начнут долбить сильнее и устроят тебе метастабильный отказ.

5xx

• 500 Internal Server Error: «мы сломались», в 99% случаев из-за необработанной паники или неожиданной ошибки. Деталей клиенту наружу не отдаём.
• 502 Bad Gateway отдаёт прокси, который сходил на апстрим и получил мусор или разрыв. Смотри бэкенд.
• 503 Service Unavailable - временно не можем: перегрузка, деплой, отключён брейкером. Вместе с ним правильно отдавать Retry-After.
• 504 Gateway Timeout: прокси не дождался апстрима. Классика: у nginx таймаут 60 с, а запрос идёт 90 с.

Content-Type и Accept

Content-Type: application/json; charset=utf-8 описывает текущее тело, Accept: application/json говорит, что клиент хочет в ответ (content negotiation). Не умеет сервер отдать запрошенный тип, отвечает 406; не понимает присланный - 415 Unsupported Media Type. На практике Content-Type из запроса решает, парсить форму или JSON, а без него браузер может начать MIME sniffing: угадает тип по содержимому и превратит загруженную картинку в исполняемый HTML. Лечится X-Content-Type-Options: nosniff.

Authorization

Схемы: Basic base64(user:pass) (только поверх TLS, пароль летит фактически открытым), Bearer <token> (JWT или opaque-токен, стандарт для API), Digest (легаси). Инфраструктуру он тоже задевает: с Authorization в запросе общим кэшам по умолчанию запрещено кэшировать ответ. И целиком этот заголовок в логи не пишут, только префикс или хэш.

X-Request-Id и трассировка

Балансировщик или самый первый сервис генерирует идентификатор запроса, кладёт в X-Request-Id и пишет в каждую строку лога. Дальше он прокидывается во все исходящие вызовы, в сообщения в брокер, в атрибуты спанов. Так по одной строке из тикета пользователя собирают весь путь запроса через десяток сервисов. Стандартом сейчас стал traceparent из W3C Trace Context (OpenTelemetry), но X-Request-Id живёт практически везде.

// Middleware: взять входящий id или создать свой, положить в контекст
func RequestID(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        id := r.Header.Get("X-Request-Id")
        if id == "" {
            id = uuid.New().String()   // Go 1.27: uuid уже в стандартной библиотеке
        }
        w.Header().Set("X-Request-Id", id)                 // вернём клиенту
        ctx := context.WithValue(r.Context(), ctxKeyReqID, id)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

Куки

Сервер ставит Set-Cookie: sid=abc; HttpOnly; Secure; SameSite=Lax; Path=/; Max-Age=86400, браузер потом сам шлёт Cookie: sid=abc на каждый подходящий запрос. Атрибуты:

• HttpOnly: JS не видит куку через document.cookie, и при XSS сессию не украсть.
• Secure - отправляется только по HTTPS.
• SameSite бывает Strict (вообще не отправлять при переходах с чужих сайтов), Lax (отправлять при обычной навигации по ссылке, но не при POST/iframe/img; дефолт в Chrome) и None (отправлять всегда, обязателен Secure). Это главная встроенная защита от CSRF.
• Domain / Path - область видимости; Max-Age / Expires - срок жизни, без них кука сессионная и живёт до закрытия браузера.

Что было в 1.1

Keep-alive (дефолт с 1.1) оставляет TCP открытым после ответа, чтобы заново не платить за рукопожатие и медленный старт. Pipelining разрешает слать несколько запросов, не дожидаясь ответов, но отвечать сервер обязан строго по порядку. Поэтому один медленный запрос запирает все следующие: это и есть HOL-блокировка прикладного уровня. Вдобавок кривые прокси ломали порядок, и браузеры конвейеризацию отключили - на практике её нет. Обходились «шардированием доменов» (img1.site.com, img2.site.com), склейкой CSS/JS и спрайтами. С HTTP/2 эти костыли стали вредны.

Что принёс HTTP/2

• Бинарный фрейминг. Вместо текста идут фреймы фиксированной структуры: HEADERS, DATA, SETTINGS, WINDOW_UPDATE, RST_STREAM, GOAWAY, PING. Парсится однозначно и быстро.
• Мультиплексирование. У каждого запроса свой stream id, фреймы разных потоков чередуются в одном соединении и собираются на той стороне. Сотне параллельных запросов хватает одного TCP-соединения и одного TLS-хендшейка.
• HPACK. Сжимает заголовки статической таблицей (61 частый заголовок), динамической таблицей на соединение и кодом Хаффмана. Повторные Cookie и User-Agent схлопываются до пары байт, а в 1.1 они летели целиком в каждом запросе.
• Приоритеты и управление потоком на уровне отдельных стримов (WINDOW_UPDATE), Server Push (оказался неудачным и де-факто мёртв).

Четыре вещи, которые QUIC решает

• HOL на транспорте. Порядок и восстановление потерь у каждого стрима свои, и потерянный пакет стрима A не задерживает данные стрима B.
• Стоимость установки. TCP+TLS 1.3 обходятся в 2 RTT (1 на SYN, 1 на TLS). QUIC совмещает транспортное и криптографическое рукопожатие в 1 RTT, а при возобновлении по билету данные летят в первом же пакете, за 0 RTT.
• Смена сети. Соединение опознаётся не по пятёрке адрес/порт, а по connection ID. Переключился с Wi-Fi на LTE, IP сменился, а соединение живо: ни рукопожатия заново, ни обрыва загрузки.
• Окостенение. TCP нельзя развивать: промежуточные железки режут незнакомые опции. QUIC шифрует почти весь заголовок, включая номера пакетов, поэтому middlebox видит только UDP и не мешает эволюции.

Цена

• Процессор. Пакеты обрабатываются в userspace, а не в ядре: нет разгрузки на сетевую карту (частично её сейчас дают UDP GSO/GRO), больше системных вызовов. Раньше разрыв был в 2–3 раза, сейчас заметно меньше, но он есть.
• UDP местами режут. Корпоративные файрволы и некоторые провайдеры блокируют UDP/443, поэтому нужен фолбэк на TCP: сервер объявляет поддержку заголовком Alt-Svc: h3=":443", а клиент пробует оба варианта.
• Инструменты. Привычный tcpdump покажет только шифрованный UDP; отладка требует ключей и свежих версий Wireshark.

Рукопожатие TLS 1.3 по шагам

1. ClientHello: версии, список шифронаборов, поддерживаемые группы, SNI (какой домен нужен), ALPN (h2/http1.1) и сразу key_share, долю ключа для той группы, которую клиент угадал.
2. ServerHello: выбранный шифронабор и свой key_share. С этого момента обе стороны уже могут вычислить общий секрет, и всё дальнейшее шифруется.
3. Сервер шифрованно шлёт Certificate, CertificateVerify (подписывает хэш всего рукопожатия приватным ключом и так доказывает владение) и Finished.
4. Клиент проверяет цепочку и подпись, шлёт Finished и в том же полёте может слать HTTP-запрос. Итого 1 RTT.

Если клиент не угадал группу, сервер отвечает HelloRetryRequest, и рукопожатие стоит 2 RTT. В TLS 1.2 полное рукопожатие - 2 RTT, есть RSA key transport без forward secrecy и живы CBC-режимы, на которые пришлась половина известных атак. TLS 1.3 всё это выкинул: осталось пять шифронаборов, все с AEAD, а обмен ключами только эфемерный, с forward secrecy (её нет лишь у возобновления по одному PSK и у 0-RTT).

Цепочка доверия

Сертификат X.509 связывает домен с публичным ключом и подписан удостоверяющим центром. Клиент строит цепочку (лист → промежуточный → корень из хранилища ОС/браузера) и проверяет подписи, сроки, соответствие имени полю SAN (Common Name как имя не используется с 2017 года), назначение ключа и отзыв (CRL; OCSP уходит - Let's Encrypt выключил его в 2025 году). Корневые ключи держат офлайн и подписывают ими только промежуточные, поэтому сервер обязан отдавать промежуточный.

SNI и mTLS

SNI несёт имя домена открытым текстом в ClientHello. Без него на одном IP не удержать много сайтов с разными сертификатами: сервер не знает, какой предъявить. Побочный эффект: наблюдателю видно, куда ты идёшь. Закрывает это расширение ECH.

В mTLS (взаимный TLS) сертификат предъявляет и клиент, а сервер проверяет его по своему пулу CA. Где применяется: межсервисный трафик в service mesh (Istio, Linkerd делают это прозрачно через сайдкар), доступ к Kubernetes API, банковские и платёжные интеграции, IoT, доступ к внутренним системам вместо VPN (модель BeyondCorp). Плюс: аутентификация без паролей и токенов, личность привязана к криптографии. Минус: свой PKI, то есть выпуск, распространение, ротация (в mesh автоматом каждые 24 часа) и отзыв.

// Сервер, требующий клиентский сертификат
srv := &http.Server{
    Addr: ":8443",
    TLSConfig: &tls.Config{
        MinVersion: tls.VersionTLS12,
        ClientAuth: tls.RequireAndVerifyClientCert, // не Request и не Verify...IfGiven
        ClientCAs:  clientCAPool,
    },
}
// Клиент с внутренним CA вместо InsecureSkipVerify
cfg := &tls.Config{RootCAs: internalPool, MinVersion: tls.VersionTLS12}

Как кэш принимает решение

1. Есть ли запись по ключу (URL + заголовки из Vary)? Нет - идём в сеть.
2. Свежа ли она (возраст меньше max-age / до Expires)? Если да, отдаём мгновенно, в сеть не ходим вообще.
3. Протухшую не выбрасываем, а делаем условный запрос с If-None-Match (или If-Modified-Since). На 304 продлеваем свежесть и отдаём старое тело, на 200 заменяем.

Директивы, которые путают

• no-cache не значит «не кэшировать». Кэшировать можно, но перед каждой отдачей обязательна ревалидация.
• А вот no-store значит «вообще не сохранять». Для персональных данных и страниц с токенами.
• private пускает только в браузер, не в CDN. public пускает и в общие кэши (и даже перебивает запрет для ответов с Authorization, штука опасная).
• immutable - не перепроверять никогда: для файлов с хэшем в имени.
• stale-while-revalidate=30: отдать протухшее сразу, а обновить фоном.

ETag против Last-Modified

ETag несёт хэш или версию содержимого и точен побайтово; W/"..." помечает слабый, «то же по смыслу». Last-Modified несёт время с точностью до секунды и два изменения внутри одной секунды не различит. Если есть оба, приоритет у ETag. Бонусом тот же механизм даёт оптимистическую блокировку на запись: If-Match: "9a1f3c", и при несовпадении сервер отвечает 412, а не затирает чужие изменения.