# Ошибки и проверки
## Перечисление `Error`
| `Io(std::io::Error)` | Файл не удалось открыть, прочитать или записать |
| `Format(String)` | Байты не соответствуют заявленному формату либо файл обрезан |
| `Unsupported(String)` | Настоящая возможность формата, которую крейт не реализует; называется явно |
| `Cast(String)` | Значение не пережило бы сужающее преобразование при `CastPolicy::Strict` |
| `InvalidArgument(String)` | Сам запрос бессмысленен: строка в `.npy`, неизвестное расширение, выделение сверх `max_alloc` |
| `Shape { expected, got }` | Объявленная форма не соответствует данным |
| `Pickle(String)` | Испорченный поток pickle или отвергнутое глобальное имя |
| `Compression(String)` | Сжатый элемент не удалось распаковать либо выключена возможность `deflate` |
| `Exhausted` | Потоковый читатель вышел за конец данных |
`Error` реализует `Display` и `std::error::Error` вручную — крейты с
процедурными макросами не подтягиваются, — поэтому он сочетается с `anyhow`,
`thiserror` или обычным `Box<dyn Error>`.
## Проверки при записи
В задании на эту библиотеку требовалось, чтобы строка никогда не записывалась
там, где ожидается массив. Эта проверка и несколько других выполняются до
создания файла, поэтому отклонённая запись не оставляет следов:
```rust,no_run
# use pyferrite::prelude::*;
let e = write("x.npy", &Value::Str("hello".into())).unwrap_err();
assert!(format!("{e}").contains("npy"));
// invalid argument: `.npy` stores a single array; `str` is not one.
// Use `.npz`, `.pkl` or `.h5` for containers.
```
Что проверяется:
- **Пригодность контейнера.** `.npy` хранит ровно один массив. Все остальные
форматы принимают вложенность.
- **Тип элементов.** Разнородный список не может стать числовым массивом, и в
ошибке сказано, какой элемент этому помешал.
- **Форма.** У `WriteOptions::shape` должно быть то же число элементов, что и у
данных, иначе будет `Error::Shape { expected, got }`. Именно это позволяет
записать `[1, 6]`, а не `[6]`, когда numpy должен увидеть вектор-строку.
- **Выразимость.** Писатель HDF5 отказывается от типа, который не умеет
выразить, а не подменяет его тихо другим.
- **Имена ссылок.** Имена в HDF5 не могут быть пустыми и содержать `/` или NUL.
- **Полнота.** `LazyWriter::finish` падает, если пришло меньше элементов, чем
было объявлено.
## Безопасность pickle
Распаковка произвольных данных в Python исполняет произвольный код. Эта
библиотека — нет: у машины попросту нет механизма, чтобы что-либо вызвать.
1. **Белый список.** `REDUCE` и `NEWOBJ` разрешаются по фиксированной таблице
конструкторов numpy, torch, `collections` и `_codecs`. Каждый реализован как
функция на Rust, строящая соответствующее `Value`.
2. **Чёрный список.** `os`, `sys`, `subprocess`, `builtins.eval`,
`builtins.exec` и их родня отвергаются с ошибкой, называющей модуль, если
не установлен `allow_unknown_globals`. С ним они инертно сохраняются, как
любой другой класс, чтобы подозрительный файл можно было изучить.
3. **Инертный захват.** Всё прочее становится `PyObject`, хранящим модуль, имя
класса и аргументы конструктора. Ничего не выполняется. Объект можно
изучить, изменить и записать обратно.
4. **Ограниченное выделение памяти.** Каждая длина, прочитанная из файла,
сверяется с `ReadOptions::max_alloc` до того, как что-либо резервируется,
поэтому заголовок, заявляющий петабайт, падает сразу.
```rust,no_run
# use pyferrite::prelude::*;
// Pickle, вызывающий os.system, отвергается, а не исполняется.
let e = read("suspicious.pkl").unwrap_err();
assert!(format!("{e}").contains("os"));
```
Это делает чтение недоверенной контрольной точки заметно безопаснее, чем
`pickle.load`, — хотя «безопаснее» не значит «безопасно», и файл из неизвестного
источника по-прежнему заслуживает подозрения.
## Устойчивость
Обрезанные и испорченные файлы дают ошибки, а не панику. Каждое чтение курсора
проверяется по границам, каждая длина сверяется с остатком входных данных, а у
обходчика заголовков объектов есть защита от циклов. Набор тестов покрывает
обрезание на нескольких смещениях и откровенный мусор для всех шести форматов.