Registry Định dạng & Magic-Byte Sniffing

Mọi truy cập tệp trong basaltic-red đều được phân giải về một FormatHandler, lớp trừu tượng pluggable trong src/engine/formats/mod.rs.

Trait FormatHandler

pub struct OpenedSource {
    pub schema: SchemaRef,
    pub batches: Box<dyn Iterator<Item = Result<RecordBatch, BazanError>> + Send>,
}

pub trait FormatHandler: Send + Sync {
    fn open(&self, file_path: &str, batch_size: usize) -> Result<OpenedSource, BazanError>;
    fn process_file(&self, engine: &MatrixEngine, file_path: &str, batch_size: usize)
        -> Result<(usize, usize, usize), BazanError>;
    fn read_range(&self, file_path: &str, offset: usize, limit: usize, batch_size: usize)
        -> Result<RecordBatch, BazanError>;
    fn open_with_columns(&self, file_path: &str, batch_size: usize, columns: &[String])
        -> Result<OpenedSource, BazanError>;
    fn read_range_columns(&self, /* ... */) -> Result<RecordBatch, BazanError>;
}

Handler trả về OpenedSource kiểu lazy, một Arrow schema kèm iterator batch dạng streaming. Reader CSV/JSON và reader cột Parquet/IPC trả trực tiếp Arrow batch; adapter Avro, MessagePack và XLSX dùng plugins/base_templates/row_chunker.rs để chuyển row đã decode thành batch.

Định dạng sẵn có

HANDLERS trong formats/mod.rs hiện đăng ký 16 extension. Các alias dùng chung handler được gom cùng hàng. Việc quét locator và định tuyến slice nằm trong map.rs và slice.rs.

Mọi slice_cols giữ thứ tự cột yêu cầu và báo lỗi nếu thiếu field. Parquet, Arrow IPC/Feather và ORC chuyển phép chiếu xuống reader; CSV/TSV/PSV/TXT trên nhánh map parse cột được chọn nhưng vẫn đọc đủ byte của record. Nhánh map JSON, Avro, MsgPack và XLSX decode khoảng dòng được chọn rồi mới project. Map chỉ dùng khi size và modification time còn khớp. Map thiếu/cũ hoặc entry không khớp thì fallback; sidecar không đọc được trả lỗi. Handler động cho extension built-in bỏ qua locator built-in. Dynamic delimited dùng plugins/base_templates/delimited.rs với delimiter/header do người đăng ký chọn.

Thứ tự phân giải Handler

resolve_handler_for_file() thử lần lượt:

1. Tra extension (handler_for), O(1), kiểm registry động trước, rồi đến bảng tĩnh. Extension chuẩn hóa về chữ thường.
2. Sniff magic-byte (sniff_format_from_file), đọc 512 byte đầu và soi qua sniff_format_from_bytes:

Các luồng dùng resolve_handler_for_file() cũng có thể mở tệp không phần mở rộng nhờ nhận diện magic byte. filter_files_parallel hiện tra handler theo extension, nên tệp đầu vào cần có extension đã đăng ký.

Đăng ký động từ Python

Registry động nằm sau RwLock<HashMap<String, Arc<dyn FormatHandler>>> và thao tác qua br.formats.*:

import basaltic_red as br

br.formats.register_delimited(ext="dat", delimiter="|", has_header=True)
print(br.formats.list_formats())     # gồm cả "dat" cùng các built-in
table = br.read.slice_rows("data/custom.dat", offset=0, limit=50)
br.formats.unregister_format("dat")  # trả True nếu từng tồn tại

handler_for() ưu tiên handler đã đăng ký hơn built-in cùng extension. API slice giữ ưu tiên này kể cả khi có Lake Map; map không ghi locator built-in cho extension bị override và slice fallback sang handler đã đăng ký. Reader DataFusion ListingTable riêng của SQL không áp dụng override động; xem SQL DataFusion.