1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203
//! Codecs for transforming values into and from binary wire format.
//!
//! All codecs in this module are wrappers around the [serde] crates implementing the
//! data representations.
//! Thus you should refer to the corresponding crate documentation for information
//! about limitations and backward as well as forward compatibility.
//!
//! # Crate features
//!
//! Each codec is gated by the corresponding crate feature `codec-*`, i.e.
//! the JSON codec is only available if the crate features `codec-json` is enabled.
//! The crate feature `full-codecs` enables all codecs.
//!
//! The default codec, named [Default](struct@Default), can be selected by enabling the
//! appropriate `default-codec-*` crate feature.
//! For example, if you want to use the JSON codec by default, enable the crate feature
//! `default-codec-json`.
//! Only one default codec feature must be enabled, otherwise a compile error will occur.
//! The default codec should only be selected by an application and not a library crate
//! that uses Remoc.
//! Otherwise a conflict between multiple libraries that depend upon different default
//! codecs will occur.
//!
//! The following features select the default codec.
//!
//! * `default-codec-bincode` -- enables and selects Bincode as the default codec
//! * `default-codec-ciborium` -- enables and selects CBOR as the default codec
//! * `default-codec-json` -- enables and selects JSON as the default codec
//! * `default-codec-message-pack` -- enables selects MessagePack as the default codec
//!
//! By default the JSON codec is enabled and the default, i.e. the `default-codec-json`
//! crate feature is enabled.
//! Thus to change the default codec, you must specify `default-features = false` when
//! referencing Remoc in your `Cargo.toml`.
//!
use serde::{de::DeserializeOwned, Deserialize, Deserializer, Serialize};
use std::{
error::Error,
fmt,
io::{Read, Write},
sync::Arc,
};
/// Reference counted error that is send, sync, static and clone.
pub type ArcError = Arc<dyn Error + Send + Sync + 'static>;
/// An error consisting of a string message.
#[derive(Debug, Clone)]
pub(crate) struct ErrorMsg(pub String);
impl fmt::Display for ErrorMsg {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
write!(f, "{}", &self.0)
}
}
impl Error for ErrorMsg {}
/// Serialization error.
#[derive(Debug, Clone)]
pub struct SerializationError(pub ArcError);
impl SerializationError {
/// Creates a new serialization error.
pub fn new<E>(err: E) -> Self
where
E: Error + Send + Sync + 'static,
{
Self(Arc::new(err))
}
}
impl fmt::Display for SerializationError {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
write!(f, "{}", &self.0)
}
}
impl Error for SerializationError {}
impl Serialize for SerializationError {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: serde::Serializer,
{
let msg = self.0.to_string();
msg.serialize(serializer)
}
}
impl<'de> Deserialize<'de> for SerializationError {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
let msg = String::deserialize(deserializer)?;
Ok(Self::new(ErrorMsg(msg)))
}
}
/// Deserialization error.
#[derive(Debug, Clone)]
pub struct DeserializationError(pub ArcError);
impl DeserializationError {
/// Creates a new deserialization error.
pub fn new<E>(err: E) -> Self
where
E: Error + Send + Sync + 'static,
{
Self(Arc::new(err))
}
}
impl fmt::Display for DeserializationError {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
write!(f, "{}", &self.0)
}
}
impl Error for DeserializationError {}
impl Serialize for DeserializationError {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: serde::Serializer,
{
let msg = self.0.to_string();
msg.serialize(serializer)
}
}
impl<'de> Deserialize<'de> for DeserializationError {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
let msg = String::deserialize(deserializer)?;
Ok(Self::new(ErrorMsg(msg)))
}
}
/// Serializes and deserializes items from and to byte data.
pub trait Codec: Send + Sync + Serialize + for<'de> Deserialize<'de> + Clone + Unpin + 'static {
/// Serializes the specified item into the data format.
fn serialize<Writer, Item>(writer: Writer, item: &Item) -> Result<(), SerializationError>
where
Writer: Write,
Item: Serialize;
/// Deserializes the specified data into an item.
fn deserialize<Reader, Item>(reader: Reader) -> Result<Item, DeserializationError>
where
Reader: Read,
Item: DeserializeOwned;
}
pub mod map;
// ============================================================================
// Codecs
// ============================================================================
#[cfg(feature = "codec-bincode")]
mod bincode;
#[cfg(feature = "codec-bincode")]
pub use self::bincode::Bincode;
#[cfg(feature = "default-codec-bincode")]
#[doc(no_inline)]
pub use self::bincode::Bincode as Default;
#[cfg(feature = "codec-ciborium")]
mod ciborium;
#[cfg(feature = "codec-ciborium")]
pub use self::ciborium::Ciborium;
#[cfg(feature = "default-codec-ciborium")]
#[doc(no_inline)]
pub use self::ciborium::Ciborium as Default;
#[cfg(feature = "codec-json")]
mod json;
#[cfg(feature = "codec-json")]
pub use json::Json;
#[cfg(feature = "default-codec-json")]
#[doc(no_inline)]
pub use json::Json as Default;
#[cfg(feature = "codec-message-pack")]
mod message_pack;
#[cfg(feature = "codec-message-pack")]
pub use message_pack::MessagePack;
#[cfg(feature = "default-codec-message-pack")]
#[doc(no_inline)]
pub use message_pack::MessagePack as Default;
/// Default codec is not set and cannot be used.
///
/// Set one of the crate features `default-codec-*` to define the default codec.
///
/// This will cause a compile error when you attempt to use it.
#[cfg(not(feature = "default-codec-set"))]
pub struct Default;