Ошибки драйвера: duplicate key и таймауты

В семнадцатом уроке вы сделали email уникальным: CreateOne с опцией unique создал индекс, и вторая вставка того же адреса упала. Сервер отвечает на дубликат кодом 11000, а драйвер превращает его в готовый предикат: mongo.IsDuplicateKeyError(err) возвращает true для кодов 11000, 11001 — дубликат при обновлении — и 12582, особого случая с capped-коллекцией. Для шардированных кластеров есть четвёртый путь: mongos упаковывает дубликат в код 16460, и хелпер узнаёт его по подстроке E11000 в сообщении. Ключевое свойство — работа с пачками: на ошибке BulkWriteException хелпер вернёт true, если дубликат обнаружен хотя бы у одной операции из пачки. Сообщение сервера при этом содержательное: E11000 duplicate key error collection с именем индекса email_1 и значением ключа — сразу видно, какой именно адрес оказался занят, и в логе это ценнее любого стека. Duplicate key — не авария, а бизнес-сигнал: адрес занят, клиенту честнее отдать 409, чем 500. Есть и вторичный путь проверки: errors.As в CommandError с равенством Code и 11000 — пригодится, когда хелпера под рукой нет, но IsDuplicateKeyError короче и покрывает больше случаев.

За предикатами стоят конкретные структуры, и знание их полей отличает точную обработку от гадания. Ошибки одиночных записей — InsertOne, UpdateOne, UpdateMany, DeleteOne, DeleteMany, ReplaceOne — приезжают типом WriteException: внутри WriteConcernError, если не подтвердилась запись, срез WriteErrors и метки. Каждый WriteError несёт Index — позицию операции в срезе, переданном в InsertMany или BulkWrite, — поля Code и Message и исходный ответ сервера. Пачки живут по своим правилам: InsertMany и BulkWrite возвращают BulkWriteException, где каждый элемент среза — BulkWriteError с тем же WriteError и Request, моделью, которая вызвала сбой. Отсюда практическое правило mongo duplicate key-обработки: предикат говорит «есть дубликат», а детали — какой документ, какой индекс — ищите циклом по WriteErrors. Отдельная ветка — CommandError: сбой самой команды, например в Find или Aggregate. У него поле Code имеет тип int32, Name — кодовое имя от сервера вроде DuplicateKey или MaxTimeMSExpired, Message, Wrapped и Raw с исходным ответом. Оба типа протаскиваются через fmt.Errorf с %w: errors.As найдёт CommandError или WriteException на любой глубине обёртки.

Первый источник — ваш собственный контекст: context.WithTimeout на операцию истёк, и драйвер прерывает работу с context.DeadlineExceeded. Второй — сервер-селекшн: перед каждой операцией драйвер выбирает подходящий живой сервер, и если за serverSelectionTimeout тот не нашёлся, возвращается ServerSelectionError. По умолчанию на выбор даётся тридцать секунд — константа defaultServerSelectionTimeout в недрах драйвера, — а текст ошибки выглядит характерно: server selection error: context deadline exceeded, current topology с перечнем серверов и последней сетевой причиной вроде connection refused. Настраивается это через SetServerSelectionTimeout или параметр serverSelectionTimeoutMS в строке подключения. Третий источник — клиентский SetTimeout: единый таймаут операций на весь клиент, механизм CSOT. Дедлайн контекста операции главнее: клиентское значение применяется только тогда, когда у контекста своего дедлайна нет. Клиентский таймаут уезжает на сервер как maxTimeMS, и его превышение оборачивается кодом 50, MaxTimeMSExpired, — это тоже таймаут, хотя родился он на сервере. Рядом живёт SetConnectTimeout — лимит на установку соединения, тоже тридцать секунд по умолчанию, а ноль означает «без лимита».

mongo.IsTimeout отвечает на вопрос «стоит ли повторить позже»: он поднимается по цепочке ошибок и возвращает true, если встретит context.DeadlineExceeded, внутренний ErrDeadlineWouldBeExceeded драйвера, ошибку ожидания соединения из пула WaitQueueTimeoutError, командный код 50 MaxTimeMSExpired, сетевой интерфейс net.Error с флагом Timeout, либо метки NetworkTimeoutError и ExceededTimeLimitError. mongo.IsNetworkError устроен иначе: он проверяет ровно одну метку, NetworkError, которую драйвер вешает на сбои обмена по уже установленному соединению — обрыв, зависший сокет, провал рукопожатия. Отсюда контринтуитивная пара, проверенная по исходникам v2.3.0: на ServerSelectionError IsTimeout отвечает true, потому что DeadlineExceeded сидит в цепочке, а IsNetworkError — false, потому что до сетевого обмена дело не дошло и метку никто не ставил. Server selection вообще происходит до первого байта запроса, поэтому выключенная база проявляется таймаутом выбора, а не сетевой ошибкой. Обрыв посреди операции — наоборот: метка NetworkError есть, а флага таймаута может не быть. Два вопроса — «медленно» и «оборвалось» — отвечают разными предикатами, и склеивать их в один разбор строк не стоит.

Кроме структур, драйвер держит несколько сентинелов, сравниваемых через errors.Is. Главный — mongo.ErrNoDocuments со словами mongo: no documents in result: FindOne.Decode по пустой выборке возвращает именно его, и это нормальный ответ, а не сбой — ветка «не найдено» пишется через errors.Is, как в уроке про FindOne. ErrClientDisconnected выпадает при обращении к клиенту после Disconnect — симптом жизненного цикла, а не сети. ErrNilDocument и ErrEmptySlice — ошибки программирования: nil-документ в CRUD и пустой срез в InsertMany, и такие ветки чинятся в коде, а не ретраятся. Теперь ретраи. Дубликат не ретраится никогда: это ответ предметной области, а для гонок апсерта лекарство известно из десятого урока — повторная попытка с тем же upsert или чтение существующего документа. При сетевом сбое во время записи драйвер сам делает одну повторную попытку — механизм retryable writes — так что ваш слой видит ошибку уже после её исчерпания. context.Canceled — это отмена, а не таймаут: IsTimeout на него не сработает и повторять его не нужно. Граница классификации упирается в HTTP: 409 на дубликат, 503 и 504 на таймауты и сеть, 404 на ErrNoDocuments, 500 на всё остальное без попыток угадывания.