Формы и загрузка файлов

HTML-форма — второй после JSON способ раздать данные серверу, и у POST-формы два режима тела. По умолчанию браузер шлёт application/x-www-form-urlencoded: тот самый формат имя=значение&имя=значение, который вы видели в query-строке четвёртого урока. Но стоит дописать в тег form атрибут enctype="multipart/form-data" — и то же самое превратится в составное тело: части склеены границей-boundary, каждое поле — свой фрагмент со своими заголовками. Именно в multipart живёт загрузка файлов: байты документа нельзя честно вложить в строку параметров, а в отдельную часть — легко. Выбор кодировки делает браузер, разгребать её — сервер, и сегодняшняя тема «fiber загрузка файлов» — про обе кодировки разом.

Терминальные двойники уже у вас в руках: curl -d шлёт urlencoded (и молча ставит этот Content-Type, если вы забыли заголовок — ловушка девятого урока, на которой построен predict десятого), а curl -F собирает multipart с boundary сам, без единого ручного заголовка. У Fiber оба формата разгребает один и тот же форм-биндер, поэтому мы пойдём по исходникам один раз, а применять будем двумя способами: текстовые поля формы — тегами и валидатором из десятого урока, файлы — вручную, потому что у валидатора нет линейки для размера.

Сверимся с исходниками тега v3.5.0. В bind.go метод Form задокументирован дословно так: Form binds the form into the struct, map[string]string and map[string][]string. If Content-Type is "application/x-www-form-urlencoded" or "multipart/form-data", it will bind the form values. Multipart file fields are supported using multipart.FileHeader, []multipart.FileHeader, or []multipart.FileHeader — четыре факта в одном абзаце: разбирает форму в структуру или карту, берёт оба Content-Type, файлы кладёт в поля-FileHeader, а ошибки возвращает по уже знакомой схеме BindError на разборе и Error со статусом 400 в авторежиме. В конце метода стоит validateStruct — та самая, из десятого урока: правила полей формы исполняются сами.

Заглянем и глубже. Bind().Body из девятого урока в switch по Content-Type держит строку case MIMEApplicationForm, MIMEMultipartForm: return b.Form(out) — оба формата заведены на один метод. Внутри binder/form.go парсер различает их по регистру: EqualFold сравнивает заголовок с multipart/form-data — и если совпало, уходит в bindMultipart, о котором ниже; иначе идёт цикл по req.PostArgs().All() — пары urlencoded собираются в карту и прогоняются через parse. Имя словаря — «form»: у полей структуры тег form, а не json. Есть и свежая опция конфига EnableSplittingOnParsers (app.go, Optional: false): если включить, значения через запятую расщепляются в срезы — для форм это поведение включается той же настройкой, что для query и заголовков.

Когда структура под форму избыточна, у Ctx есть семья точечных методов — в v3.5.0 они объявлены на Req, а Ctx отдаёт их как свои (в тестах исходников это c.FormValue("name")). FormValue(key string, defaultValue ...string) string возвращает первое значение по ключу и — цитата документации — Defaults to the empty string "" if the form value doesn't exist: отсутствие ключа не ошибка, а пустая строка или ваш дефолт. FormFile(key string) (multipart.FileHeader, error) достаёт файл: docs формулируют — the first file from the given key is returned, первый файл по ключу; ошибка вернётся, если multipart не разобрался. MultipartForm() (multipart.Form, error) отдаёт форму целиком — Value для текстовых полей и File для файлов, к которым вернёмся ниже; parse-ing ограничен BodyLimit, docs: Parsing is bounded by the app BodyLimit.

Два честных штриха из сверки. Первый: FormValueAny из v2 в v3 не переехал — точных типов больше нет, для них существует Bind в структуру. Второй: у всех трёх методов есть общее побочное действие — на форм-запросе они нормализуют Content-Type (приводят регистр multipart/form-data и boundary= к каноническому виду, иначе fasthttp с его чувствительностью к регистру не найдёт границу). Заголовок переписывается в байтах запроса: если вам нужен исходный Content-Type — скопируйте его до первого FormValue, алертом об этом служит caution в документации.

Multipart-запрос по запросу «multipart fiber» лежит в тех же исходниках, что и всё остальное: binder/form.go, метод bindMultipart. Схема тела проста: части отрезаны друг от друга границей boundary, случайной строкой из заголовка Content-Type; каждая часть несёт заголовки Content-Disposition (имя поля и, для файлов, имя файла) и Content-Type части. Браузер проставляет всё это из enctype="multipart/form-data", curl -F — сам; руками boundary не собирают никогда.

Что делает Fiber. bindMultipart зовёт req.MultipartFormWithLimit(b.MaxBodySize) — и это место, где конфиг встречается с парсером: в bind.go строка bind.MaxBodySize = b.ctx.App().config.BodyLimit присваивает лимит телу биндеру. Дальше карта раскладывается на два словаря: multipartForm.Value — текстовые поля, multipartForm.File — файлы, map[string][]*multipart.FileHeader; оба прогоняются через formatBindData и один общий parse. Итого форм-биндер не различает «форму с файлами» и «форму без файлов»: один вход Bind().Form, один parse, один validateStruct — различие только в том, есть ли в multipartForm.File хоть одна часть с filename. Проверить, что вы имеете дело с multipart, не разбирая тело, можно методом IsMultipart() — docs: Reports whether the Content-Type header is multipart form data.

Для нескольких файлов под одним именем поля документация закрепляет ровно три варианта типа поля: multipart.FileHeader — первый файл, []multipart.FileHeader — все файлы, []multipart.FileHeader — то же с указателем. На стороне формы полю ставится атрибут multiple, а curl повторяет -F "attachments=@a.pdf" -F "attachments=@b.pdf" — два файла под одним ключом. В структуру они ложатся как Attachments []*multipart.FileHeader с тегом form:"attachments": парсинг всё тот же, файлы приходят срезом.

Второй путь — без структуры: через c.MultipartForm() достать *multipart.Form и взять form.File["attachments"] — docs показывают ровно этот шаблон в примере: files := form.File["documents"], затем цикл с fmt.Println(file.Filename, file.Size, file.Header["Content-Type"][0]) и c.SaveFile(file, ...) на каждой итерации. Здесь нужна одна честная поправка из сверки исходников: метода c.File() в v3 нет — файлы достаются либо FormFile (первый), либо MultipartForm (все), либо Bind().Form в срез; не ищите «итератор файлов» и в методе Next() — тот относится к цепочке middleware из шестого урока, к файлам отношения не имеет. Если план урока или старая статья обещают c.File — это след из другой версии, в теге v3.5.0 такого метода на Ctx нет.

Пара методов записи на Ctx — с ними сверимся построчно. Первая: SaveFile(fh multipart.FileHeader, path string) error — docs: Method is used to save any multipart file to disk. Внутри ctx.go две строки: nil-заголовок даёт ErrFileHeaderNil — errors.New("file: file header is nil") из error.go, иначе вызов fasthttp.SaveMultipartFile(fileheader, path): файл создаётся по точному пути, какой вы передали. Вторая: SaveFileToStorage(fileheader multipart.FileHeader, path string, storage Storage) error — Method is used to save any multipart file to an external storage system. Здесь файл читается в память с ограничением: maxUploadSize берётся из c.app.config.BodyLimit, fileheader.Size проверяется заранее, затем io.LimitReader(file, int64(maxUploadSize)+1) — и если буфер оказался больше лимита, возвращается ErrFileRead, обёрнутый вокруг fasthttp.ErrBodyTooLarge, вместе с именем файла через fmt.Errorf("%w: %q: %w", ...). Запись выполняет storage.SetWithContext(c.Context(), path, data, 0) — Storage из Fiber: в примере документации это memory.New(), но интерфейс реализуют и S3-адаптеры.

И одна поправка, ради которой стоило перечитать исходники: метода SaveFileToDisk в v3 нет — это имя из v2, в теге v3.5.0 пара выглядит как SaveFile (диск) и SaveFileToStorage (внешнее хранилище). Если встретите SaveFileToDisk в чужом коде Fiber — перед вами либо v2, либо опечатка; компилятор v3 его не знает. Обе функции возвращают ошибки уже обёрнутыми: ErrFileOpen при неудачном открытии, ErrFileRead при неудачном чтении, ErrFileStore при провале хранилища — все с именем файла внутри, все распаковываются errors.Is.

fiber.Config.BodyLimit (app.go) описан так: Max body size that the server accepts. Zero or negative values fall back to the default limit — и ниже Default: 4 1024 1024; константа DefaultBodyLimit = 4 1024 1024 живёт там же. Документация договаривает последствия: If the size exceeds the configured limit, it sends 413 - Request Entity Too Large response, и перечисляет, где именно лимит действует — в том числе when parsing multipart form data via Ctx.MultipartForm(). В app.go за это отвечает строка errors.Is(err, fasthttp.ErrBodyTooLarge) → ErrRequestEntityTooLarge — превышение тела превращается в готовую *Error со статусом 413 ещё до вашего хендлера.

Для уроков про файлы из этого следуют три вывода. Первый: лимит общий на ЗАПРОС, а не на файл — три вложения по два мегабайта уложатся в 6 МиБ и упрутся в дефолт; считайте бюджет формы перед тем, как поднимать цифру. Второй: подняли BodyLimit — выросли и буферы разбора; 16 МиБ на хендлер задач расточительно, для вложений честнее валидировать fh.Size каждого файла и держать общий лимит умеренным. Третий: у SaveFileToStorage лимит тот же — он читает файл в память и упирается в тот же maxUploadSize, так что «напишу в хранилище, минуя лимит» не выйдет: либо конфиг, либо уменьшение файлов.

Загрузка файлов — крупнейшая поверхность атаки из всех тем курса, и все три защиты стоят копейки. Первая — имя. Filename приходит из Content-Disposition части, и клиент волен прислать там ../../etc/hosts: наивный конкатенированный путь уведёт запись выше каталога. Лечение — filepath.Base: функция отрезает все каталоги и оставляет базовое имя; парой к ней идут filepath.Ext и strings.ToLower для расширения. Вторая — расширение из белого списка: map[string]bool с разрешёнными значениями, всё вне списка — отказ. Не строите чёрные списки запрещённых расширений: список запретов всегда короче списка бед.

Третья — содержимое. fh.Header["Content-Type"] — заявленный тип, не проверенный никем; настоящий тип узнаёт http.DetectContentType(head[:n]) по первым 512 байтам — стандартный сниффер mime-таблицы. Порядок проверок в хендлере важен: размер (fh.Size) — до чтения, расширение — до чтения содержимого, сниффинг — последним, когда дешёвые проверки уже отсеяли мусор. Две дисциплины напоследок: храните файлы под СВОИМИ именами (префикс с временем или счётчиком — коллизии и повторные атаки на одно имя исчезают), каталог создавайте os.MkdirAll заранее, и тогда SaveFile не упрётся в отсутствующий путь.

Десятый урок обещал, что формы пройдут проверку бесплатно, — сверим обещание с bind.go: validateStruct стоит после Form так же, как после Body, JSON и Query. Значит, на TaskForm с validate-тегами works required,min=3,max=100 на title и oneof на priority — из curl -d, из браузерной формы, из multipart: источник разбора валидатору неважен, это и была главная мысль tip-а десятого урока, теперь подкреплённая собственными хендлерами. Проваленная проверка прилетит в err как validator.ValidationErrors, и ветка errors.As из десятого урока вернёт 400 со списком {field, rule, param} — для формы ответ будет тем же словарём, что и для JSON.

Файлы из этого контракта выпадают ровно на одну ступень. validateStruct видит поле *multipart.FileHeader как обычный указатель на структуру: required на нём сработает — nil-указатель считается пустым и правило провалится, поэтому «файл обязателен» можно выразить тегом. Но правила про размер и содержимое в словаре validator отсутствуют: линейки у валидатора нет. Размер — fh.Size и сравнение с константой, содержимое — http.DetectContentType, количество файлов — len(in.Files): всё это пишется руками в хендлере сразу после Bind, как в безопасном варианте выше. Итого мост с десятого урока достроен: поля формы — тегами, файлы — кодом, и обе проверки живут в одном хендлере рядом.

Соберите каркас — конфиг с валидатором из десятого урока, слои восьмого (helmet, cors, logger), страж седьмого, группа /api — и прогоните пять сценариев. Первый: форма создания задачи, curl -d "title=позвонить клиенту&priority=high" на /api/tasks/form — 201 и задача с id; validateStruct проверил поля бесплатно. Второй: короткий title, -d "title=пв" — 400 и {"errors":[{"field":"title","rule":"min","param":"3"}]}: форма ошибок десятого урока в действии. Третий: один файл, curl -F "note=логотип" -F "avatar=@logo.png" на /api/tasks/preview — 201, в ответе имя и размер из FileHeader. Четвёртый: три вложения через повторяющиеся -F "attachments=@..." на /api/tasks/attachments — 201 и список сохранённых путей; два файла под скалярным полем вернули бы один — predict выше показал почему. Пятый: подмена имени, -F "avatar=@notes.txt;filename=../../evil.txt" — в безопасном хендлере отказ по белому списку, в наивном — запись вне uploads; попутно отправьте файл на 5 МиБ и получите 413 от BodyLimit.

Материал держится на трёх опорах: валидация полей — из десятого урока, форма ошибок и Content-Type-диспетчер Bind — из девятого, страж и слои — из седьмого и восьмого; полный план — на странице курса Fiber. Отдельный привет пятому уроку: там c.SendFile отдавала файлы клиенту, а сегодня мы научились их принимать — поставьте их рядом, и цикл «загрузил — сохранил — раздал» замкнётся. Песочница сайта сетевые сценарии не запускает — runner-ов в уроках Fiber нет, интерактивы здесь quiz, predict, fill, order и флешкарты; каркас собирайте локально в терминале.

Дальше — двенадцатый урок: Cookie и сессии. Загруженные вложения захотят знать, кто их прикрепил: Set/Get cookie, session middleware и хранилища дадут запросу память о пользователе — а форма входа, кстати, будет отправляться тем самым Bind().Form из этого урока.