fix doc and add tests for migrate.rs

This commit is contained in:
Alex 2023-01-03 15:53:13 +01:00
parent d6d571d512
commit 33f25d26c7
Signed by untrusted user: lx
GPG key ID: 0E496D15096376BE

View file

@ -1,19 +1,21 @@
use serde::{Deserialize, Serialize}; use serde::{Deserialize, Serialize};
/// Indicates that this type has an encoding that can be migrated from
/// a previous version upon upgrades of Garage.
pub trait Migrate: Serialize + for<'de> Deserialize<'de> + 'static { pub trait Migrate: Serialize + for<'de> Deserialize<'de> + 'static {
/// A sequence of bytes to add at the beginning of the serialized /// A sequence of bytes to add at the beginning of the serialized
/// string, to identify that the data is of this version. /// string, to identify that the data is of this version.
const VERSION_MARKER: &'static [u8] = b""; const VERSION_MARKER: &'static [u8] = b"";
/// The previous version of this data type, from which items of this version /// The previous version of this data type, from which items of this version
/// can be migrated. Set `type Previous = NoPrevious` to indicate that this datatype /// can be migrated.
/// is the initial schema and cannot be migrated.
type Previous: Migrate; type Previous: Migrate;
/// This function must be filled in by implementors to migrate from a previons iteration /// The migration function that transforms a value decoded in the old format
/// of the data format. /// to an up-to-date value.
fn migrate(previous: Self::Previous) -> Self; fn migrate(previous: Self::Previous) -> Self;
/// Decode an encoded version of this type, going through a migration if necessary.
fn decode(bytes: &[u8]) -> Option<Self> { fn decode(bytes: &[u8]) -> Option<Self> {
let marker_len = Self::VERSION_MARKER.len(); let marker_len = Self::VERSION_MARKER.len();
if bytes.len() >= marker_len && &bytes[..marker_len] == Self::VERSION_MARKER { if bytes.len() >= marker_len && &bytes[..marker_len] == Self::VERSION_MARKER {
@ -25,6 +27,7 @@ pub trait Migrate: Serialize + for<'de> Deserialize<'de> + 'static {
Self::Previous::decode(bytes).map(Self::migrate) Self::Previous::decode(bytes).map(Self::migrate)
} }
/// Encode this type with optionnal version marker
fn encode(&self) -> Result<Vec<u8>, rmp_serde::encode::Error> { fn encode(&self) -> Result<Vec<u8>, rmp_serde::encode::Error> {
let mut wr = Vec::with_capacity(128); let mut wr = Vec::with_capacity(128);
wr.extend_from_slice(Self::VERSION_MARKER); wr.extend_from_slice(Self::VERSION_MARKER);
@ -36,14 +39,13 @@ pub trait Migrate: Serialize + for<'de> Deserialize<'de> + 'static {
} }
} }
/// Indicates that this type has no previous encoding version to be migrated from.
pub trait InitialFormat: Serialize + for<'de> Deserialize<'de> + 'static { pub trait InitialFormat: Serialize + for<'de> Deserialize<'de> + 'static {
/// A sequence of bytes to add at the beginning of the serialized /// A sequence of bytes to add at the beginning of the serialized
/// string, to identify that the data is of this version. /// string, to identify that the data is of this version.
const VERSION_MARKER: &'static [u8] = b""; const VERSION_MARKER: &'static [u8] = b"";
} }
// ----
impl<T: InitialFormat> Migrate for T { impl<T: InitialFormat> Migrate for T {
const VERSION_MARKER: &'static [u8] = <T as InitialFormat>::VERSION_MARKER; const VERSION_MARKER: &'static [u8] = <T as InitialFormat>::VERSION_MARKER;
@ -54,6 +56,7 @@ impl<T: InitialFormat> Migrate for T {
} }
} }
/// Internal type used by InitialFormat, not meant for general use.
#[derive(Serialize, Deserialize)] #[derive(Serialize, Deserialize)]
pub struct NoPrevious; pub struct NoPrevious;
@ -72,3 +75,85 @@ impl Migrate for NoPrevious {
unreachable!() unreachable!()
} }
} }
#[cfg(test)]
mod test {
use super::*;
#[derive(Serialize, Deserialize, PartialEq, Eq, Debug)]
struct V1 {
a: usize,
b: String,
}
impl InitialFormat for V1 {}
#[derive(Serialize, Deserialize, PartialEq, Eq, Debug)]
struct V2 {
a: usize,
b: Vec<String>,
c: String,
}
impl Migrate for V2 {
const VERSION_MARKER: &'static [u8] = b"GtestV2";
type Previous = V1;
fn migrate(prev: V1) -> V2 {
V2 {
a: prev.a,
b: vec![prev.b],
c: String::new(),
}
}
}
#[test]
fn test_v1() {
let x = V1 {
a: 12,
b: "hello".into(),
};
let x_enc = x.encode().unwrap();
let y = V1::decode(&x_enc).unwrap();
assert_eq!(x, y);
}
#[test]
fn test_v2() {
let x = V2 {
a: 12,
b: vec!["hello".into(), "world".into()],
c: "plop".into(),
};
let x_enc = x.encode().unwrap();
assert_eq!(&x_enc[..V2::VERSION_MARKER.len()], V2::VERSION_MARKER);
let y = V2::decode(&x_enc).unwrap();
assert_eq!(x, y);
}
#[test]
fn test_migrate() {
let x = V1 {
a: 12,
b: "hello".into(),
};
let x_enc = x.encode().unwrap();
let xx = V1::decode(&x_enc).unwrap();
assert_eq!(x, xx);
let y = V2::decode(&x_enc).unwrap();
assert_eq!(
y,
V2 {
a: 12,
b: vec!["hello".into()],
c: "".into(),
}
);
let y_enc = y.encode().unwrap();
assert_eq!(&y_enc[..V2::VERSION_MARKER.len()], V2::VERSION_MARKER);
let z = V2::decode(&y_enc).unwrap();
assert_eq!(y, z);
}
}