Дедлайны и отмены

В уроке про unary вы уже ставили таймаут на вызов: context.WithTimeout, defer cancel, Invoke вернул DeadlineExceeded — и шестнадцать строк кода казались всей темой. Но этот фрагмент прятал три вопроса, без которых дедлайны в проде не живут. Первый: что именно едет по сети, когда клиент ставит срок? Не «две секунды» как константа, а остаток времени до дедлайна, пересчитанный в момент отправки, — и на сервере этот остаток снова превращается в дедлайн от чужого «сейчас». Второй: кто и когда принудительно останавливает работу? Оказывается, минимум трое: клиентский Invoke, серверный транспорт со своим таймером и сам хендлер — и только последний из них опционален, остальные гарантированы библиотекой. Третий: что происходит в цепочке сервисов, когда один вызов порождает другой? Дедлайн не сбрасывается и не копится — он сжимается, и в этом сжатии участвует сам язык: правила контекстного дерева Go делают правильное поведение дефолтным. Четырнадцатый урок разбирает всё это по винтикам. Каталог тринадцатого урока дал нам два кода — DeadlineExceeded и Canceled; сейчас они станут не строчками в таблице, а результатами конкретных таймеров и вызовов cancel(). Метод-пример прежний — GetOrder и CreateOrder сервиса заказов; для каскада появится соседний сервис платежей, которому хендлер заказов звонит внутри своей работы. И оговорка заранее: дедлайн — единственная часть контекста вызова, которая распространяется по сети сама; метаданные распространяются иначе, и в середине урока мы аккуратно разведём эти два механизма.

Начнём с терминологии, потому что слова «таймаут» и «дедлайн» часто используют как синонимы, а в контекстном пакете Go за ними стоит строгое различие. Таймаут — это длительность: «дай три секунды с текущего момента». Дедлайн — это точка во времени: «успей до 17:32:15.250». В док-комментарии пакета context связь между ними сформулирована дословно: «WithTimeout returns WithDeadline(parent, time.Now().Add(timeout))» — таймаут это всего лишь удобная форма дедлайна, где точка вычисляется от «сейчас». А сам WithDeadline описан так: «WithDeadline returns a derived context that points to the parent context but has the deadline adjusted to be no later than d. If the parent's deadline is already earlier than d, WithDeadline(parent, d) is semantically equivalent to parent» — дедлайн производного контекста «не позже d», и если родитель уже живёт с более ранним сроком, функция семантически эквивалентна WithCancel: новый таймер не заводится вовсе. В исходниках это видно буквально: «if cur, ok := parent.Deadline(); ok && cur.Before(d) { // The current deadline is already sooner than the new one. return WithCancel(parent) }». Это правило минимума — фундамент каскадов из второй половины урока: продлить дедлайн через производный контекст невозможно, можно только сжать. Третий игрок — WithCancel: «The returned context's Done channel is closed when the returned cancel function is called or when the parent context's Done channel is closed, whichever happens first» — без срока, чистая отмена, и тоже подчиняющаяся родителю. У любого контекста есть метод Deadline() (time.Time, bool): пара «точка во времени, есть ли она вообще» — ок-флаг false означает, что срока нет и таймер не заведён. У Background() срока нет никогда; у контекста из grpc-вызова — есть, если клиент его поставил. Поэтому таймауты grpc-вызовов на практике означают одну операцию: посадить в ctx точку во времени — через WithTimeout, через WithDeadline или унаследовав её от родителя, — а дальше дерево контекста и библиотека сделают остальное.

Заголовок grpc-timeout вы уже видели в трассировке шестого урока: две секунды уезжают как «2S», двести пятьдесят миллисекунд как «250m». Но в том уроке нас интересовала кодировка; теперь интересует смысл, и он тоньше, чем «клиент переслал свой таймаут». Клиент не пересылает длительность, которую вы написали в WithTimeout. Он вызывает ctx.Deadline() у того контекста, который вы передали в вызов, вычисляет time.Until(deadline) — остаток до точки во времени, — и вот этот остаток кодируется в заголовок функцией EncodeDuration, которую шестой урок разбирал по исходникам grpcutil. Разница видна в двух ситуациях. Первая: контекст вызова производный, с чужим дедлайном — скажем, вы получили запрос с остатком в одну секунду и позвонили соседу с этим ctx как есть; на провод уедет не «ваш» таймаут, которого вы не ставили, а остаток родительского срока. Каскадное сжатие начинается прямо здесь, ещё до всякого сервера. Вторая: между установкой дедлайна и отправкой запроса прошло время — остаток уже меньше исходных двух секунд, и в заголовке будет именно он. Серверная половина — зеркальный пересчёт. http2_server.go разбирает заголовки вызова, находит grpc-timeout и декодирует его функцией decodeTimeout: восемь цифр плюс буква единицы — всё, что длиннее или невалидно, — ошибка, и вызов встречает Internal с сообщением «malformed grpc-timeout» ещё до хендлера. Декодированная длительность интерпретируется как срок от серверного «сейчас»: библиотека создаёт контекст потока вызовом WithTimeout с этим значением — и хендлер получает в ctx свой собственный дедлайн, равный по смыслу клиентскому, но уже привязанный к чужим часам. Отсюда два практических вывода. Первый: дедлайн по сети едет как остаток, а не как абсолютная метка — расхождение часов клиента и сервера съедается из бюджета вызова, и для больших значений это надо помнить при диагностике «куда делось сто миллисекунд». Второй: сервер не может «увидеть исходный таймаут» — только то, что осталось; продлить срок изнутри нельзя в принципе, и это не недоработка, а смысл механизма.

Для unary-вызова дедлайн прилетает первым аргументом хендлера — тем самым ctx, который вы передаёте дальше в репозиторий и соседние вызовы. Для стриминговых моделей контекст тот же по смыслу, но добывается методом: stream.Context(), и док-комментарий к нему лаконичен: «Context returns the context for this stream» — девятый урок уже слушал этот канал в bidi-чате. Теперь важно понять, откуда он берётся и что в нём лежит. На приёмной стороне grpc-go заводит контекст потока так: если заголовок grpc-timeout присутствовал — context.WithTimeout(ctx, timeout) с декодированным остатком; если нет — context.WithCancel(ctx), контекст без срока, который кончится только вместе с соединением или явной отменой. Отсюда прямое следствие, которое часто удивляет: вызов от клиента без таймаута приходит хендлеру с контекстом, у которого ctx.Deadline() возвращает ok=false. Срока нет — не «огромный», а именно никакого; таймер не заведён, и проверка «дедлайн уже прошёл» в вашем коде просто не сработает. Второй сюрприз — серверный таймер транспорта. Создавая поток с дедлайном, транспорт запускает собственный таймер на остаток: при истечении он вызывает closeStream со статусом CANCEL — кодом протокола HTTP/2, — а та ветка в обязательном порядке дёргает cancel() контекста потока. То есть у дедлайна два независимо сработавших конца: клиентский Invoke вернёт DeadlineExceeded ровно в свой срок, а серверный транспорт в свой срок принудительно закроет поток, даже если хендлер игнорирует ctx.Done() полностью. Хендлер при этом не убивается: горутина продолжит крутиться, пока сама не заглянет в Done() или не закончит работу, — но её ответ уже некуда доставить: поток закрыт. Клиентская симметрия для полноты: у стрима тоже есть Context(), но его док-комментарий предупреждает «It should not be called until after Header or RecvMsg has returned. Once called, subsequent client-side retries are disabled» — вызов до первого Recv отключает клиентские ретраи, и это мост к пятнадцатому уроку: библиотека умеет повторять вызовы сама, если ей не мешать.

В каталоге тринадцатого урока DeadlineExceeded стоял четвёртым номером среди кодов, которые фреймворк генерирует сам. Теперь видно, где именно генерирует: минимум в трёх местах, и у каждого своя роль. Первое — клиентский http2_client.go перед отправкой заголовков: остаток не положительный — отказ немедленно, запрос не покидает процесс. Второе — toRPCErr в rpc_util.go: любая контекстная ошибка context.DeadlineExceeded, поднявшаяся из ожидания ответа, переписывается в готовый статус errContextDeadline = status.Error(codes.DeadlineExceeded, context.DeadlineExceeded.Error()). Третье — серверная сторона: транспортный таймер закрывает поток, а хендлер, если он дисциплинирован, сам возвращает FromContextError(ctx.Err()) с тем же кодом. Важно, что во всех трёх случаях сообщение — «context deadline exceeded», текст из пакета context, а не человеческая легенда: док-контракт кода из codes.go стоит прочесть целиком, потому что в нём спрятано главное производственное следствие. «DeadlineExceeded means operation expired before completion. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire» — вызов, меняющий состояние, к моменту DeadlineExceeded мог УСПЕТЬ выполниться: списание прошло, заказ создан, письмо ушло — а ответ не доехал в срок. Клиент видит «не успели», система — «успели, но вы не в курсе». Именно поэтому ретрай после DeadlineExceeded для неидемпотентной операции — это не ускорение, а задвоение: пятнадцатый урок соберёт вокруг этого правила политику повторов, а пока держите вывод — код DeadlineExceeded честно сообщает про ваш бюджет, но ничего не говорит о том, дошла ли работа до конца на той стороне. Второй вывод — про связку с сообщением: раз текст фиксированный, «улучшать» его нечем и незачем; вся контекстуализация — какой именно вызов, какой заказ, какой остаток — это забота ваших логов и метрик, а не grpc-message.

Дедлайн — это отмена по расписанию; вторая половина механизма — отмена по решению. context.WithCancel даёт контекст без срока: «The returned context's Done channel is closed when the returned cancel function is called or when the parent context's Done channel is closed, whichever happens first» — закрытие по вашему вызову cancel() или по родителю, что случится раньше. Подставьте такой контекст в grpc-вызов, а потом позовите cancel() посреди работы — и механика разовьётся по проводу сама. Клиентский транспорт закрывает HTTP/2-поток кадром RST_STREAM с кодом CANCEL: на серверной стороне handleRSTStream вызывает closeStream, а closeStream — уже знакомую по дедлайну цепочку — дёргает cancel() контекста потока. Хендлер видит ctx.Done() с context.Canceled; для стримов это те же Canceled из Recv и Send, что девятый урок разбирал на двух горутинах чата. Клиентский Invoke тем временем выходит с кодом Canceled, и сообщение здесь тоже фиксированное: errContextCanceled в rpc_util.go — это status.Error(codes.Canceled, context.Canceled.Error()), то есть дословно «context canceled». Док-комментарий кода из каталога подтверждает право собственности: «Canceled indicates the operation was canceled (typically by the caller)» — обычно отменил сам вызывающий, и библиотека честно превращает это в код №1. Когда выбирать cancel вместо deadline? Когда срок не измеряется часами: пользователь закрыл страницу — сессия bidi-чата из девятого урока кончается WithCancel по решению оператора; upstream-сервис прислал «этот запрос больше не нужен»; клиентский код понял, что ответ уже бесполезен. Дедлайн отвечает на вопрос «на сколько дать бюджет», cancel — «когда убить по сигналу». И последнее, что сбивает с толку новичков: defer cancel() после УСПЕШНОГО вызова не «отменяет результат» — поток уже завершён, closeStream на готовом потоке просто досыпает cleanup, и результат остаётся у вас. Отмена живёт только пока вызов жив.

Вот где дедлайны становятся архитектурой. Хендлер CreateOrder внутри своей работы звонит сервису платежей: один RPC порождает другой. Какой контекст дать дочернему вызову — и что окажется на проводе? Вариант первый — передать входящий ctx как есть. Дочерний вызов прочитает ctx.Deadline() — ту же самую точку во времени, — вычислит остаток в момент отправки и уедет в grpc-timeout с ним. Остаток меньше того, что клиент послал сервису заказов: часть бюджета съедена собственной работой хендлера. Каждое звено цепочки откусывает от общего бюджета — дедлайн сжимается автоматически, без единой строки специального кода: в этом весь смысл расчёта остатка вместо пересылки константы. Вариант второй — WithTimeout(ctx, 200time.Millisecond): дочерний вызов получает собственный, заведомо меньший срок. Это и есть дисциплина «каждый уровень выделяет часть бюджета»: платёжный звонок не должен съедать весь остаток, оставив запись в базу без времени. Правило минимума гарантирует, что ошибиться в большую сторону нельзя: если родительский остаток внезапно меньше ваших двухсот миллисекунд, WithDeadline вернёт WithCancel с комментарием исходников «The current deadline is already sooner than the new one» — таймер не заведётся, и срок останется родительским. Вариант третий — «щедрый» WithTimeout(ctx, 10time.Second) при родительском остатке в полторы секунды: новичок ожидает, что дочерний вызов получит десять секунд, — нет: ten больше остатка, правило минимума срабатывает, дедлайн остаётся родительским. Продлить срок дочернему вызову невозможно — только сузить. Что увидит дочерний вызов, когда родительский бюджет сгорел? Дерево контекста отменяет детей с ошибкой родителя: дочерний ctx получает context.DeadlineExceeded, и его Invoke выходит кодом DeadlineExceeded — причина пробегает вниз по цепочке, не меняясь по смыслу. Так «распространение отмены» работает в обе стороны: cancel() и дедлайн сверху убивают всё поддерево, а нижние звенья честно отчитываются тем же кодом.

Контекст вызова носит и срок, и данные, и важно не свалить их в одну кучу. Дедлайн и отмена — активная механика: таймеры, каналы Done, дерево, где отмена родителя мгновенно срабатывает у всех потомков, где значение остатка пересчитывается на каждом витке по сети. context.Value — пассивный словарь: ключ кладётся, ключ читается, никаких событий и таймеров. В gRPC-мире данные вызова распространяются собственным механизмом библиотеки, о котором говорил десятый урок: metadata.AppendToOutgoingContext поверх входящего контекста — и на провод заголовки уезжают отдельно от grpc-timeout, своей жизнью. Если нужно «прокинуть» вниз по цепочке trace-id или флаг ретрая — это метаданные, а не Value и уж точно не дедлайн. Внутри контекста потока библиотека держит и служебные значения: входящие метаданные достаются metadata.FromIncomingContext, данные TLS-пира из двенадцатого урока — peer.FromContext, — но всё это читается по ключам и ни на что не «реагирует». Дедлайн же нельзя ни положить в метаданные, ни передать строкой: это не данные, а состояние — таймер, который тикает на каждой машине заново, от чужих часов. Практическое правило разведения механизмов звучит так: то, что должно ВЫЖИТЬ истечение срока, едет в метаданных (они не зависят от таймеров); то, что должно УМЕРЕТЬ вместе с вызовом, держится на контексте с дедлайном. Попытка натянуть срок на Value — классическая ошибка проектирования: строку «deadline: 2s» прочитают, но никто не отменит работу, когда она истечёт. Контекст обязан управлять жизнью вызова — только через встроенные в него таймеры и Done-каналы, а не через договорённости «прочитай мою строчку и обещай».

Соберём все исходы урока в одну карту — что именно возвращается клиенту при каждом виде беды. Дедлайн истёк — DeadlineExceeded с фиксированным «context deadline exceeded»: свой Invoke в свой срок, серверный транспорт в свой, хендлер в свой Done(). Кто-то позвал cancel() — Canceled с «context canceled»; право вызова принадлежит вашему коду, и отличить одну отмену от другой — уже ваша забота: по коду, а не по сообщению. Обрыв соединения — Unavailable: в toRPCErr транспортная ConnectionError переписывается именно в этот код, и тринадцатый урок напоминал, что это единственный код с обещанием «повтор с бэкоффом имеет смысл» — при условии идемпотентности. Обрыв посреди сообщения — Internal: io.ErrUnexpectedEOF, когда тело сообщения оборвалось на середине, библиотека квалифицирует как «something is very broken» — и это правильно, потому что полуразобранное сообщение означает нарушение протокола, а не чистую сеть. Отдельная честность про гонки: если соединение умирает одновременно с горящим дедлайном, клиент увидит тот код, чей источник первым заметит беду, — здесь нет ни детерминизма, ни гарантий порядка, и клиентский код обязан ветвиться равноправно, не строя логику «сперва проверяю дедлайн, потом сеть». Для стриминговых вызовов карта та же, но ошибки распределяются по горутинам: Send и Recv узнают о бедах по-разному, и девятый урок уже показывал, как читать правду в bidi. Общий принцип карты: код говорит категорию беды, сообщение — почти никогда; всё человеческое — в ваших логах, метриках и traceback'ах.

Отдельная честная оговорка про формат: в самоучителе есть песочница с интерпретатором Go, но сеть в браузере недоступна — поднять сервер и позвонить ему оттуда нельзя, поэтому runner-ов в этом уроке, как и во всём gRPC-курсе, нет. Всё разобранное проверяется локально за десять минут на паре из четвёртого и пятого уроков. Три эксперимента на вечер. Первый: хендлер с time.Sleep(5s), клиент с WithTimeout(2s) — убедитесь, что клиент получает DeadlineExceeded в свой срок, а лог сервера без ветки Done() покажет работу впустую; добавьте порции с select из урока — и сравните. Второй: замените таймаут на WithCancel и вызовите cancel() через сто миллисекунд — клиент увидит Canceled, сервер — Canceled в ctx.Err(); затем добавьте defer cancel() после успешного вызова и проверьте, что результат не «отменился». Третий: поднимите второй сервис-сосед и позвоните ему из хендлера — сравните grpc-timeout на обоих участках, передавая ctx как есть и оборачивая в WithTimeout(200ms). Дальше по маршруту: пятнадцатый урок — повторы и ретраи: service config и retryPolicy превращают карту ошибок этого урока в автоматическое поведение клиента, а вопрос «повторять ли после DeadlineExceeded» получит строгий ответ через идемпотентность. До этого стоит перечитать урок про статус-коды — ветвление по DeadlineExceeded и Canceled из этого урока устроено ровно тем аппаратом, и урок про unary — базовая анатомия вызова с его таймаутами. Отмену в живом стриме с двумя горутинами мы уже слышали в уроке про bidi. Полный маршрут курса — на странице gRPC-Go.