Задача, которую он решает

Один входящий запрос порождает десятки горутин: сервисный слой, три параллельных запроса к БД, вызов внешнего API, запись в кэш. Клиент отвалился через 200 мс, и вся эта работа стала бессмысленной, но продолжает жечь CPU, держать соединения из пула и место в памяти. Без общего механизма каждый слой пришлось бы связывать своим done-каналом и передавать его руками через все сигнатуры.

Context даёт ровно такой done-канал, только со стандартным интерфейсом из четырёх методов, который понимают database/sql, net/http, gRPC, драйверы Kafka и вообще вся экосистема. Ценна тут именно стандартизация: любая библиотека умеет отменяться одинаково.

Дерево

• Корнем служит context.Background(), он никогда не отменяется и не имеет дедлайна. Это emptyCtx, буквально пустая структура.
• Каждый WithCancel/WithTimeout/WithValue создаёт новый контекст-потомок, ссылающийся на родителя. Родитель о потомке знает через карту children (только отменяемые потомки в ней есть).
• Отмена родителя рекурсивно отменяет всех потомков. Отмена потомка на родителя не влияет: сигнал ходит только вниз.
• Дедлайн наследуется по минимуму: потомок не может жить дольше родителя. WithTimeout(ctx, time.Hour) внутри запроса с бюджетом 200 мс не даст ничего.

Механика отмены

Done() возвращает <-chan struct{}, который при отмене закрывается. Закрытие канала будит сразу всех, кто на нём ждёт, и повторное чтение из закрытого канала возвращает нулевое значение мгновенно. Поэтому один и тот же контекст можно проверять из любого числа горутин без всяких блокировок. Сам канал создаётся лениво: если Done() никто не звал, канала в структуре нет.

Разбор по одному

• WithCancel(parent) отменяется только по явному вызову cancel(). Для фоновых воркеров, конвейеров, «останови всё, если один упал». Возвращает cancelCtx.
• WithTimeout(parent, d) - отмена через интервал. 95% случаев в продовом коде: «запрос к платёжке не дольше 800 мс». Внутри лежит timerCtx, то есть cancelCtx + time.Timer, который при срабатывании зовёт ту же cancel с DeadlineExceeded.
• WithDeadline(parent, t) отменяет в абсолютный момент. Нужен, когда бюджет делится между последовательными шагами: три вызова по WithTimeout(ctx, 1s) дадут суммарно 3 секунды, а один WithDeadline сверху честно ограничит весь запрос секундой. Так обычно и делают «сквозной дедлайн», передавая его в заголовке между сервисами.
• WithValue(parent, k, v) стоит особняком: это valueCtx, у него нет ни отмены, ни таймера, ни карты детей. Одно значение на узел; поиск Value(k) идёт линейно вверх по цепочке до корня. Отсюда правило: не наворачивать десятки значений, каждое это лишний узел и лишний шаг поиска.

Стоимость

WithValue стоит одну маленькую аллокацию, поиск идёт за O(глубины). WithCancel добавляет к аллокации запись в карту children родителя под мьютексом. WithTimeout делает то же самое плюс таймер в куче таймеров рантайма. На горячем пути с миллионом RPS это заметно, а в обычном сервисе это шум рядом с сетевым вызовом.

Что ловят

Почему это понадобилось

До Go 1.20 весь мир видел в логах ровно две строки: context canceled и context deadline exceeded. Кто отменил, на каком уровне и из-за чего, оставалось загадкой. В сервисе с errgroup и десятью параллельными вызовами это означало, что при падении одного из них девять остальных писали в лог бесполезное context canceled, а настоящая ошибка терялась.

var errTooManyRetries = errors.New("исчерпаны ретраи")

ctx, cancel := context.WithCancelCause(parent)
defer cancel(nil)                       // nil = штатное завершение

go func() {
    if err := doRetries(ctx); err != nil {
        cancel(fmt.Errorf("%w: %v", errTooManyRetries, err))
    }
}()

<-ctx.Done()
ctx.Err()                               // context.Canceled, всегда
context.Cause(ctx)                      // "исчерпаны ретраи: dial tcp: i/o timeout"
errors.Is(context.Cause(ctx), errTooManyRetries)  // true: причину можно матчить

Детали, которые отличают знающего

• Cause наследуется вниз. Причина хранится в узле, где произошла отмена; потомки, отменённые каскадом, отдают ту же причину. Поэтому её видно из самой глубины стека.
• На неотменённом контексте Cause возвращает nil, ровно как и Err().
• Если причину не задали (обычный WithCancel), Cause вернёт то же, что Err(). То есть звать Cause вместо Err() в логах безопасно всегда.
• Go 1.21 добавил WithTimeoutCause и WithDeadlineCause: при истечении Err() будет DeadlineExceeded, а Cause отдаст твою ошибку вроде errBillingSlow. Удобно, когда в цепочке несколько таймаутов и надо понять, чей сработал.
• errgroup с 1.20 внутри использует WithCancelCause, так что причиной отмены группы становится ошибка первой упавшей горутины.

Почему первым аргументом и с именем ctx

Это конвенция всей стандартной библиотеки: func (db *DB) QueryContext(ctx context.Context, query string, args ...any). Единообразие даёт дешёвый греп (grep -rn "ctx context.Context" находит все отменяемые точки), позволяет линтерам вроде contextcheck и containedctx работать, и делает обёртки-мидлвари механическими. Исключение только одно: контекст не передают в конструкторы объектов, живущих дольше вызова.

Почему не хранить в полях структуры

// Антипаттерн
type Service struct {
    ctx context.Context      // чей это контекст? какого запроса?
    db  *sql.DB
}
func (s *Service) Get(id int) (*User, error) {
    return s.db.QueryRowContext(s.ctx, ...)   // отменится, когда отменится... что-то
}

Сервис живёт весь аптайм, он синглтон. Контекст запроса живёт 200 мс. Положишь один в другой, и получишь либо вечный контекст (тогда отмена не работает вовсе), либо контекст первого запроса, отмена которого убьёт все последующие. Плюс гонка: поле пишется и читается из разных горутин. Линтер containedctx в golangci-lint ловит это правилом. Легальное исключение признано самим стандартом: http.Request, где контекст неотделим от объекта запроса и меняется через r.WithContext(ctx), создающий копию.

Почему WithValue - не для зависимостей

• Нет типобезопасности. ctx.Value(k).(*sql.DB) приводит тип в рантайме. Убрали значение из мидлвари, и узнаешь об этом паникой в проде, а не ошибкой компиляции.
• Нет видимости зависимостей. Сигнатура func Handle(ctx context.Context) ничего не говорит о том, что функции нужны БД, логгер и кэш. Явные параметры или поля структуры документируют себя сами.
• Ключ обязан быть своим неэкспортируемым типом. Строковый ключ "user" может совпасть с чужим из библиотеки и молча перетереться. Потому линтер staticcheck (проверка SA1029) и ругается на встроенные типы в ключах; в стандартном go vet такой проверки нет.
• Что класть можно: request id, trace id / span, user id и роли после аутентификации, локаль, флаги A/B-теста, дедлайн-подсказки. То есть всё, что относится к конкретному запросу и нужно на всех уровнях, но бизнес-параметром функции не считается.

Механика

На каждое принятое соединение сервер запускает conn.serve. Внутри, пока выполняется хендлер, работает фоновое чтение (startBackgroundRead): оно ждёт данных, чтобы поймать либо новый пайплайненный запрос, либо закрытие. Если чтение вернуло EOF или ECONNRESET, вызывается cancelCtx, и контекст запроса отменяется с context.Canceled. В HTTP/2 то же самое делает RST_STREAM или закрытие стрима.

func handler(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()
    select {
    case res := <-doWork(ctx):
        json.NewEncoder(w).Encode(res)
    case <-ctx.Done():
        // клиент ушёл, сработал TimeoutHandler или вызван srv.Close
        log.Info("отменено", "err", ctx.Err(), "cause", context.Cause(ctx))
        return          // писать в w бессмысленно, но безопасно
    }
}

Четыре причины отмены r.Context()

1. Клиент разорвал соединение или отменил стрим.
2. Сработал http.TimeoutHandler. Server.WriteTimeout контекст не отменяет: он лишь ставит дедлайн на запись в сокет, а хендлер работает дальше.
3. Вызван Server.Close: он рвёт соединения. Shutdown контекст не отменяет, даже когда вышел его дедлайн, поэтому после него и зовут Close.
4. ServeHTTP просто вернул управление: контекст отменяется всегда, даже при успешном ответе.

БД

// Правильно
rows, err := db.QueryContext(ctx, "select id, name from users where org = $1", orgID)
tx, err := db.BeginTx(ctx, &sql.TxOptions{Isolation: sql.LevelReadCommitted})
_, err = tx.ExecContext(ctx, "update balances set amount = amount - $1 where id = $2", sum, id)

// Неправильно: эти формы отмену вообще не видят
rows, err := db.Query(...)   // внутри это QueryContext(context.Background(), ...)

Контекст в database/sql работает на трёх уровнях. Во-первых, ожидание свободного соединения из пула прерывается по ctx.Done(): при исчерпанном пуле запрос падает с context deadline exceeded вместо бесконечного ожидания. Во-вторых, драйвер, реализующий QueryerContext, обрывает запрос, и дальше всё зависит от драйвера: pgx и lib pq шлют серверу CancelRequest (отдельное соединение с сообщением отмены), а go-sql-driver/mysql никакого KILL QUERY не шлёт, просто закрывает сокет, и запрос на сервере может доработать до конца. В-третьих, это цена отмены: соединение, на котором отменили запрос, все три драйвера закрывают, и database/sql выбрасывает его из пула, а не возвращает. Частые отмены - это частые переподключения.

HTTP-клиент

req, _ := http.NewRequestWithContext(ctx, http.MethodPost, url, body)
resp, err := client.Do(req)

При отмене Transport закрывает соединение (в HTTP/2 шлёт RST_STREAM), а Do возвращает ошибку, обёрнутую *url.Error. Проверять надо через errors.Is(err, context.DeadlineExceeded), а не сравнением строк. И отдельно: resp.Body закрывай всегда, иначе соединение не вернётся в пул и никакая отмена не поможет.

Иерархия таймаутов

• Общий бюджет запроса ставит WithDeadline в мидлвари, например 3 с.
• Пер-вызов: WithTimeout на каждый внешний вызов, меньше бюджета. БД 500 мс, биллинг 800 мс. Дедлайн наследуется, так что суммарно всё равно не выйдет за 3 с.
• client.Timeout - грубая страховка на весь запрос, включая чтение тела; контекст точнее, и ставить его надо в дополнение, а не вместо.
• Ретраи считают оставшийся бюджет: d, ok := ctx.Deadline(), и если до дедлайна меньше, чем средняя длительность вызова, ретрай не начинают.

Канонический код

ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()

errCh := make(chan error, 1)
go func() { errCh <- srv.ListenAndServe() }()

select {
case err := <-errCh:
    if !errors.Is(err, http.ErrServerClosed) {
        log.Fatal(err)                  // порт занят и подобное
    }
case <-ctx.Done():
    log.Info("получен сигнал, останавливаемся")
}
stop()                                  // вернуть дефолтный обработчик: второй Ctrl+C убьёт сразу

shutCtx, cancel := context.WithTimeout(context.Background(), 25*time.Second)
defer cancel()
if err := srv.Shutdown(shutCtx); err != nil {
    log.Warn("таймаут graceful, рвём соединения")
    _ = srv.Close()
}

Что делает Shutdown по шагам

1. Помечает сервер как закрывающийся и закрывает слушающие сокеты: новых соединений ОС уже не принимает (клиенты получат connection refused, поэтому балансировщик надо вывести из ротации ЗАРАНЕЕ).
2. Сразу, не дожидаясь запросов, запускает зарегистрированные RegisterOnShutdown хуки, каждый в своей горутине: там обычно закрывают WebSocket-соединения, которые Shutdown не видит.
3. Закрывает все idle keep-alive соединения.
4. В цикле с растущим интервалом (от 1 мс до 500 мс) проверяет, остались ли активные запросы, и ждёт, пока их не станет ноль либо не истечёт переданный контекст.

Порядок в реальном сервисе

Сначала readiness-проба возвращает 503 (или сервис снимают из балансировщика), потом несколько секунд ждут, чтобы трафик перестал приходить. Потом srv.Shutdown с дедлайном чуть меньше, чем terminationGracePeriodSeconds в Kubernetes (иначе прилетит SIGKILL посреди уборки). Потом останавливают консьюмеры и воркеры, потом закрывают пулы БД и Redis, последним идёт flush метрик и трейсов.

Шаг 1: сигнал

Нужен примитив «оповестить неизвестное заранее число слушателей, один раз, навсегда». Таким свойством обладает ровно одна операция с каналом: close. Закрытие будит всех ожидающих, и любое последующее чтение возвращается мгновенно. Отправка значений не годится, её прочитает ровно один получатель.

Шаг 2: иерархия

type myCtx struct {
    mu       sync.Mutex
    done     chan struct{}
    err      error
    children map[*myCtx]struct{}
    deadline time.Time
    timer    *time.Timer
}

func WithCancel(p *myCtx) (*myCtx, func()) {
    c := &myCtx{done: make(chan struct{}), children: map[*myCtx]struct{}{}}
    p.mu.Lock()
    if p.err != nil {                 // родитель уже мёртв, и ребёнок рождается мёртвым
        p.mu.Unlock()
        c.cancel(p.err)
        return c, func() {}
    }
    p.children[c] = struct{}{}
    p.mu.Unlock()
    return c, func() { c.cancel(errCanceled); p.remove(c) }
}

func (c *myCtx) cancel(err error) {
    c.mu.Lock()
    if c.err != nil {                 // идемпотентность
        c.mu.Unlock()
        return
    }
    c.err = err
    close(c.done)                     // будим всех своих слушателей
    kids := c.children
    c.children = nil
    if c.timer != nil {
        c.timer.Stop()
    }
    c.mu.Unlock()

    for k := range kids {             // каскад вниз, вне лока, иначе дедлок на детях
        k.cancel(err)
    }
}

Шаг 3: дедлайн и значения

Таймаут собирается из time.AfterFunc(d, func(){ c.cancel(errDeadline) }) плюс наследование: если у родителя дедлайн раньше, свой таймер не нужен вовсе. Значения живут в отдельном типе-обёртке с одной парой ключ/значение и рекурсивным поиском вверх; он неотменяемый и потому не участвует в дереве отмены.

Грабли, о которые спотыкаются на доске

Типовой пример

// Плохо: получили ctx и не используем его
func fetch(ctx context.Context, urls []string) []Result {
    ch := make(chan Result)              // небуферизованный
    for _, u := range urls {
        go func(u string) {
            ch <- get(u)                 // встанет навсегда, если читатель ушёл
        }(u)
    }
    var out []Result
    for range urls {
        select {
        case r := <-ch:
            out = append(out, r)
        case <-ctx.Done():
            return out                   // вышли, а N горутин навсегда заперты на ch
        }
    }
    return out
}

Утечка здесь ровно в том, что отправители не знают об отмене. Чинится двумя независимыми способами: сделать канал буферизованным на len(urls), чтобы отправка никогда не блокировала, либо научить отправителя смотреть на контекст.

// Хорошо, вариант 1: буфер под все результаты, отправка никогда не блокирует
ch := make(chan Result, len(urls))

// Хорошо, вариант 2: отправитель уважает отмену
go func(u string) {
    select {
    case ch <- get(u):
    case <-ctx.Done():                   // читателя больше нет, уходим
    }
}(u)

Другие сценарии

• Долгий цикл без проверки. В for _, row := range millionRows { heavy(row) } отмену не смотрят ни разу. Лечится select { case <-ctx.Done(): return ctx.Err(); default: } в начале итерации (это неблокирующая проверка, стоит единицы наносекунд).
• time.Sleep вместо таймера. Спящая горутина не отменяема. Меняй на select { case <-time.After(d): case <-ctx.Done(): } или timer := time.NewTimer(d); defer timer.Stop().
• Вызов без Context-варианта. db.Query, http.Get, conn.Read без дедлайна: контекст есть, а отменять нечего. Для голых сокетов помогает conn.SetReadDeadline плюс context.AfterFunc(ctx, func(){ conn.Close() }).
• Фон, переживший запрос. С go audit(r.Context(), ev) проблема обратная: не утечка, а мгновенная смерть задачи. Нужен context.WithoutCancel.

Как ловить

• Метрика runtime.NumGoroutine() в мониторинге: монотонный рост под ровной нагрузкой почти всегда означает утечку.
• go tool pprof http://host/debug/pprof/goroutine: в профиле видно, на какой строке заблокированы тысячи одинаковых горутин.
• go.uber.org/goleak в TestMain уронит тест, если после него остались лишние горутины. Дешевле всего ловить именно тут.