This is a Serde implementation for DAG-CBOR. It can be use in conjunction with ipld-core.
The underlying library for CBOR encoding/decoding is cbor4ii. Their Serde implementation is used as a basis. A copy of their code was copied into this repo on April 2022 and is used under the MIT/Apache-2.0 license, with permission from @quininer.
This crate started as a fork of serde_cbor, thanks everyone involved there.
Storing and loading Rust types is easy and requires only minimal modifications to the program code.
use serde_derive::{Deserialize, Serialize};
use std::error::Error;
use std::fs::File;
use std::io::BufReader;
// Types annotated with `Serialize` can be stored as DAG-CBOR.
// To be able to load them again add `Deserialize`.
#[derive(Debug, Serialize, Deserialize)]
struct Mascot {
name: String,
species: String,
year_of_birth: u32,
}
fn main() -> Result<(), Box<dyn Error>> {
let ferris = Mascot {
name: "Ferris".to_owned(),
species: "crab".to_owned(),
year_of_birth: 2015,
};
let ferris_file = File::create("examples/ferris.cbor")?;
// Write Ferris to the given file.
// Instead of a file you can use any type that implements `io::Write`
// like a HTTP body, database connection etc.
serde_ipld_dagcbor::to_writer(ferris_file, &ferris)?;
let tux_file = File::open("examples/tux.cbor")?;
let tux_reader = BufReader::new(tux_file);
// Load Tux from a file.
// Serde IPLD DAG-CBOR performs roundtrip serialization meaning that
// the data will not change in any way.
let tux: Mascot = serde_ipld_dagcbor::from_reader(tux_reader)?;
println!("{:?}", tux);
// prints: Mascot { name: "Tux", species: "penguin", year_of_birth: 1996 }
Ok(())
}The decoding of data is as strict as possible. When enabling this feature, it's a bit less strict. If you run into decoding errors for your not fully DAG-CBOR compliant data, try this feature flag first.
Sometimes it is desired that a CID is not accidentally deserialized into bytes. This can happen because the intermediate serde data model does not retain enough information to be able to differentiate between a bytes container and a CID container when there is a conflicting choice to be made, as in the case of some enum cases. The no-cid-as-bytes feature can be enabled in order to error at runtime in such cases.
The problem with that feature is, that it breaks Serde's derive attributes for internally tagged enums (#[serde(tag = "sometag")]) and untagged enums (#serde(untagged)). If this feature is enabled and you still need similar functionality, you could implement a deserializer manually. Examples of how to do that are in the enum example.
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.