puffin/
file_format.rs

1// Copyright 2023 Greptime Team
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! # Format specification for Puffin files
16//!
17//! ## File structure
18//!
19//! Magic Blob₁ Blob₂ ... Blobₙ Footer
20//!
21//! - `Magic` is four bytes 0x50, 0x46, 0x41, 0x31 (short for: Puffin Fratercula arctica, version 1),
22//! - `Blobᵢ` is i-th blob contained in the file, to be interpreted by application according to the footer,
23//! - `Footer` is defined below.
24//!
25//! ## Footer structure
26//!
27//! Magic FooterPayload FooterPayloadSize Flags Magic
28//!
29//! - `Magic`: four bytes, same as at the beginning of the file
30//! - `FooterPayload`: optionally compressed, UTF-8 encoded JSON payload describing the blobs in the file, with the structure described below
31//! - `FooterPayloadSize`: a length in bytes of the `FooterPayload` (after compression, if compressed), stored as 4 byte integer
32//! - `Flags`: 4 bytes for boolean flags
33//!   * byte 0 (first)
34//!     - bit 0 (lowest bit): whether `FooterPayload` is compressed
35//!     - all other bits are reserved for future use and should be set to 0 on write
36//!   * all other bytes are reserved for future use and should be set to 0 on write
37//!     A 4 byte integer is always signed, in a two’s complement representation, stored little-endian.
38//!
39//! ## Footer Payload
40//!
41//! Footer payload bytes is either uncompressed or LZ4-compressed (as a single LZ4 compression frame with content size present),
42//! UTF-8 encoded JSON payload representing a single [`FileMetadata`] object.
43//!
44//! [`FileMetadata`]: ../file_metadata/struct.FileMetadata.html
45
46pub mod reader;
47pub mod writer;
48
49use bitflags::bitflags;
50
51pub const MAGIC: [u8; 4] = [0x50, 0x46, 0x41, 0x31];
52
53pub const MAGIC_SIZE: u64 = MAGIC.len() as u64;
54pub const MIN_FILE_SIZE: u64 = MAGIC_SIZE + MIN_FOOTER_SIZE;
55pub const FLAGS_SIZE: u64 = 4;
56pub const PAYLOAD_SIZE_SIZE: u64 = 4;
57pub const MIN_FOOTER_SIZE: u64 = MAGIC_SIZE * 2 + FLAGS_SIZE + PAYLOAD_SIZE_SIZE;
58
59bitflags! {
60    #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
61    pub struct Flags: u32 {
62        const DEFAULT = 0b00000000;
63
64        const FOOTER_PAYLOAD_COMPRESSED_LZ4 = 0b00000001;
65    }
66}
puffin/file_format.rs

puffin/
file_format.rs
