From efb3f7316745755cefaa1f3b4e7b6e1250b4a656 Mon Sep 17 00:00:00 2001 From: Mrinal Wadhwa Date: Sat, 30 Jan 2021 09:52:46 -0800 Subject: [PATCH] feat(rust): ockam_core crate v0.1.0 1. Add docs 2. Add changelog and readme 3. Add tests 4. Restructure errors 5. Bump version --- implementations/rust/examples/node/Cargo.lock | 2 +- .../rust/examples/worker/Cargo.lock | 2 +- implementations/rust/ockam/ockam/Cargo.lock | 2 +- .../rust/ockam/ockam_core/CHANGELOG.md | 12 ++ .../rust/ockam/ockam_core/Cargo.lock | 2 +- .../rust/ockam/ockam_core/Cargo.toml | 16 +- .../rust/ockam/ockam_core/DEVELOP.md | 1 + implementations/rust/ockam/ockam_core/LICENSE | 1 + .../rust/ockam/ockam_core/README.md | 60 ++++++++ .../rust/ockam/ockam_core/src/error.rs | 141 ++++++++++++++++-- .../ockam_core/src/error/no_std_error.rs | 14 -- .../ockam/ockam_core/src/error/std_error.rs | 29 ---- .../rust/ockam/ockam_core/src/lib.rs | 20 ++- .../rust/ockam/ockam_node/Cargo.lock | 2 +- .../rust/ockam/ockam_vault/Cargo.lock | 2 +- .../rust/ockam/ockam_vault_core/Cargo.lock | 2 +- 16 files changed, 246 insertions(+), 62 deletions(-) create mode 100644 implementations/rust/ockam/ockam_core/CHANGELOG.md create mode 120000 implementations/rust/ockam/ockam_core/DEVELOP.md create mode 120000 implementations/rust/ockam/ockam_core/LICENSE create mode 100644 implementations/rust/ockam/ockam_core/README.md delete mode 100644 implementations/rust/ockam/ockam_core/src/error/no_std_error.rs delete mode 100644 implementations/rust/ockam/ockam_core/src/error/std_error.rs diff --git a/implementations/rust/examples/node/Cargo.lock b/implementations/rust/examples/node/Cargo.lock index 557c17a8303..d8c6360dc3e 100644 --- a/implementations/rust/examples/node/Cargo.lock +++ b/implementations/rust/examples/node/Cargo.lock @@ -156,7 +156,7 @@ dependencies = [ [[package]] name = "ockam_core" -version = "0.0.0" +version = "0.1.0" [[package]] name = "ockam_node" diff --git a/implementations/rust/examples/worker/Cargo.lock b/implementations/rust/examples/worker/Cargo.lock index b7a637fd666..78c33f1609c 100644 --- a/implementations/rust/examples/worker/Cargo.lock +++ b/implementations/rust/examples/worker/Cargo.lock @@ -142,7 +142,7 @@ dependencies = [ [[package]] name = "ockam_core" -version = "0.0.0" +version = "0.1.0" [[package]] name = "ockam_node" diff --git a/implementations/rust/ockam/ockam/Cargo.lock b/implementations/rust/ockam/ockam/Cargo.lock index ebb5ea3d1e9..858f8a69611 100644 --- a/implementations/rust/ockam/ockam/Cargo.lock +++ b/implementations/rust/ockam/ockam/Cargo.lock @@ -173,7 +173,7 @@ dependencies = [ [[package]] name = "ockam_core" -version = "0.0.0" +version = "0.1.0" [[package]] name = "ockam_node" diff --git a/implementations/rust/ockam/ockam_core/CHANGELOG.md b/implementations/rust/ockam/ockam_core/CHANGELOG.md new file mode 100644 index 00000000000..b5ffa67842b --- /dev/null +++ b/implementations/rust/ockam/ockam_core/CHANGELOG.md @@ -0,0 +1,12 @@ +# Changelog + +All notable changes to this crate will be documented in this file. + +The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## v0.1.0 - 2021-01-30 +### Added + +- `Error` - an error type that can be returned is both `std` and `no_std` modes. +- `Result` - a result type that can be returned is both `std` and `no_std` modes. diff --git a/implementations/rust/ockam/ockam_core/Cargo.lock b/implementations/rust/ockam/ockam_core/Cargo.lock index e97ec5dadea..f33719236a2 100644 --- a/implementations/rust/ockam/ockam_core/Cargo.lock +++ b/implementations/rust/ockam/ockam_core/Cargo.lock @@ -2,4 +2,4 @@ # It is not intended for manual editing. [[package]] name = "ockam_core" -version = "0.0.0" +version = "0.1.0" diff --git a/implementations/rust/ockam/ockam_core/Cargo.toml b/implementations/rust/ockam/ockam_core/Cargo.toml index 7a273aa5c8f..a47a2e34150 100644 --- a/implementations/rust/ockam/ockam_core/Cargo.toml +++ b/implementations/rust/ockam/ockam_core/Cargo.toml @@ -1,10 +1,24 @@ [package] name = "ockam_core" -version = "0.0.0" +version = "0.1.0" authors = ["Ockam Developers"] edition = "2018" license = "Apache-2.0" +homepage = "https://github.com/ockam-network/ockam" +repository = "https://github.com/ockam-network/ockam/implementations/rust/ockam/ockam_core" +readme = "README.md" +keywords = ["ockam"] +categories = ["no-std"] +description = """ +Core types of the Ockam library. +""" +exclude = [ + "DEVELOP.md", + "LICENSE" +] [features] default = ["std"] + +# Requires the Rust Standard Library. std = [] diff --git a/implementations/rust/ockam/ockam_core/DEVELOP.md b/implementations/rust/ockam/ockam_core/DEVELOP.md new file mode 120000 index 00000000000..dc269248358 --- /dev/null +++ b/implementations/rust/ockam/ockam_core/DEVELOP.md @@ -0,0 +1 @@ +../../DEVELOP.md \ No newline at end of file diff --git a/implementations/rust/ockam/ockam_core/LICENSE b/implementations/rust/ockam/ockam_core/LICENSE new file mode 120000 index 00000000000..14776154326 --- /dev/null +++ b/implementations/rust/ockam/ockam_core/LICENSE @@ -0,0 +1 @@ +../../../../LICENSE \ No newline at end of file diff --git a/implementations/rust/ockam/ockam_core/README.md b/implementations/rust/ockam/ockam_core/README.md new file mode 100644 index 00000000000..8c1f44118cc --- /dev/null +++ b/implementations/rust/ockam/ockam_core/README.md @@ -0,0 +1,60 @@ +# ockam_core + +[![crate][crate-image]][crate-link] +[![docs][docs-image]][docs-link] +[![license][license-image]][license-link] +[![discuss][discuss-image]][discuss-link] + +Ockam is a library for building devices that communicate securely, privately +and trustfully with cloud services and other devices. + +This crate contains the core types of the [Ockam][main-ockam-crate-link] +library and is intended for use by crates that provide features and add-ons +to the main [Ockam][main-ockam-crate-link] library. + +The main [Ockam][main-ockam-crate-link] crate re-exports types defined in +this crate. + +## Usage + +Add this to your `Cargo.toml`: + +``` +[dependencies] +ockam_core = "0.1.0" +``` + +## Crate Features + +The `ockam_core` crate has a Cargo feature named `"std"` that is enabled by +default. In order to use this crate in a `no_std` context this feature can +disabled as follows + +``` +[dependencies] +ockam_core = { version = "0.1.0", default-features = false } +``` + +Please note that Cargo features are unioned across the entire dependency +graph of a project. If any other crate you depend on has not opted out of +`ockam_core` default features, Cargo will build `ockam_core` with the std +feature enabled whether or not your direct dependency on `ockam_core` +has `default-features = false`. + +## License + +This code is licensed under the terms of the [Apache License 2.0][license-link]. + +[main-ockam-crate-link]: https://crates.io/crates/ockam + +[crate-image]: https://img.shields.io/crates/v/ockam_core.svg +[crate-link]: https://crates.io/crates/ockam_core + +[docs-image]: https://docs.rs/ockam_core/badge.svg +[docs-link]: https://docs.rs/ockam_core + +[license-image]: https://img.shields.io/badge/License-Apache%202.0-green.svg +[license-link]: https://github.com/ockam-network/ockam/blob/HEAD/LICENSE + +[discuss-image]: https://img.shields.io/badge/Discuss-Github%20Discussions-ff70b4.svg +[discuss-link]: https://github.com/ockam-network/ockam/discussions diff --git a/implementations/rust/ockam/ockam_core/src/error.rs b/implementations/rust/ockam/ockam_core/src/error.rs index a3571d7475a..c338fcb3181 100644 --- a/implementations/rust/ockam/ockam_core/src/error.rs +++ b/implementations/rust/ockam/ockam_core/src/error.rs @@ -1,15 +1,138 @@ -// --- -// Export std_error if standard library is present. +//! Error and Result types #[cfg(feature = "std")] -mod std_error; -#[cfg(feature = "std")] -pub use std_error::*; +use std::fmt::{Display, Formatter}; + +/// The type of errors returned by Ockam functions. +/// +/// This type has two implementations that are switched depending on +/// whether the `"std"` Cargo feature is enabled. +/// +/// # std +/// When the `"std"` feature is enabled and the Rust Standard Library is +/// available, the `Error` stores: +/// +/// 1. __Error Code__: A `u32` representing the the presise error. +/// 2. __Error Domain__: An error domain string. +/// +/// # no_std +/// When the `"std"` feature is not enabled we assume that the Rust Standard +/// Library is not available, the `Error` stores: +/// +/// 1. __Error Code__: A `u32` representing the the presise error. +/// +#[derive(Debug)] +pub struct Error { + code: u32, + + #[cfg(feature = "std")] + domain: &'static str, +} -// --- -// Export no_std_error if standard library is not present. +/// The type returned by Ockam functions. +#[cfg(feature = "std")] +pub type Result = std::result::Result; +/// The type returned by Ockam functions. #[cfg(not(feature = "std"))] -mod no_std_error; +pub type Result = core::result::Result; + +impl Error { + /// Creates a new [`Error`]. + #[cfg(not(feature = "std"))] + pub fn new(code: u32) -> Self { + Self { code } + } + + /// Creates a new [`Error`]. + #[cfg(feature = "std")] + pub fn new(code: u32, domain: &'static str) -> Self { + Self { code, domain } + } + + /// Returns an error's domain. + #[cfg(feature = "std")] + #[inline] + pub fn domain(&self) -> &'static str { + &self.domain + } + + /// Returns an error's code. + #[inline] + pub fn code(&self) -> u32 { + self.code + } +} + +#[cfg(feature = "std")] +impl Display for Error { + fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result { + write!( + f, + "Error {{ code: {}, domain: \"{}\" }}", + self.code, self.domain + ) + } +} + +#[cfg(feature = "std")] +impl std::error::Error for Error {} + +#[cfg(feature = "std")] +#[cfg(test)] +mod std_test { + use super::*; + + #[test] + fn can_be_created() { + let _error = Error::new(1000, "SOME_ERROR_DOMAIN"); + } + + #[test] + fn code_returns_provided_code() { + let error = Error::new(1000, "SOME_ERROR_DOMAIN"); + assert_eq!(error.code(), 1000); + assert_eq!(error.code, 1000); + } + + #[test] + fn domain_returns_provided_domain() { + let error = Error::new(1000, "SOME_ERROR_DOMAIN"); + assert_eq!(error.domain(), "SOME_ERROR_DOMAIN"); + assert_eq!(error.domain, "SOME_ERROR_DOMAIN"); + } + + #[test] + fn can_be_displayed() { + let error = Error::new(1000, "SOME_ERROR_DOMAIN"); + assert_eq!( + format!("{}", error), + "Error { code: 1000, domain: \"SOME_ERROR_DOMAIN\" }" + ); + } + + #[test] + fn can_be_debugged() { + let error = Error::new(1000, "SOME_ERROR_DOMAIN"); + assert_eq!( + format!("{:?}", error), + "Error { code: 1000, domain: \"SOME_ERROR_DOMAIN\" }" + ); + } +} + #[cfg(not(feature = "std"))] -pub use no_std_error::*; +#[cfg(test)] +mod no_std_test { + // These following tests are only run when the std feature in not enabled + // cargo test --no-default-features + + use super::*; + + #[test] + fn can_be_created_and_code_returns_provided_code() { + let error = Error::new(1000); + assert_eq!(error.code(), 1000); + assert_eq!(error.code, 1000); + } +} diff --git a/implementations/rust/ockam/ockam_core/src/error/no_std_error.rs b/implementations/rust/ockam/ockam_core/src/error/no_std_error.rs deleted file mode 100644 index 5599b353a89..00000000000 --- a/implementations/rust/ockam/ockam_core/src/error/no_std_error.rs +++ /dev/null @@ -1,14 +0,0 @@ -#[derive(Debug)] -pub struct Error { - code: u32, -} - -impl Error { - pub fn new(code: u32) -> Self { - Self { code } - } - - pub fn code(&self) -> u32 { - self.code - } -} diff --git a/implementations/rust/ockam/ockam_core/src/error/std_error.rs b/implementations/rust/ockam/ockam_core/src/error/std_error.rs deleted file mode 100644 index 847ae05fa86..00000000000 --- a/implementations/rust/ockam/ockam_core/src/error/std_error.rs +++ /dev/null @@ -1,29 +0,0 @@ -use std::fmt::{Display, Formatter, Result}; - -#[derive(Debug)] -pub struct Error { - code: u32, - domain: &'static str, -} - -impl Error { - pub fn new(code: u32, domain: &'static str) -> Self { - Self { code, domain } - } - - pub fn code(&self) -> u32 { - self.code - } - - pub fn domain(&self) -> &'static str { - &self.domain - } -} - -impl Display for Error { - fn fmt(&self, f: &mut Formatter<'_>) -> Result { - write!(f, "Error code: {}, domain: {}", self.code, self.domain) - } -} - -impl std::error::Error for Error {} diff --git a/implementations/rust/ockam/ockam_core/src/lib.rs b/implementations/rust/ockam/ockam_core/src/lib.rs index da7a3e82126..74fa719f1aa 100644 --- a/implementations/rust/ockam/ockam_core/src/lib.rs +++ b/implementations/rust/ockam/ockam_core/src/lib.rs @@ -1,7 +1,23 @@ -// --- -// #![no_std] if the standard library is not present. +//! Core types of the Ockam library. +//! +//! This crate contains the core types of the Ockam library and is intended +//! for use by other crates that provide features and add-ons to the main +//! Ockam library. +//! +//! The main Ockam crate re-exports types defined in this crate. +#![deny( + missing_docs, + trivial_casts, + trivial_numeric_casts, + unsafe_code, + unused_import_braces, + unused_qualifications, + warnings +)] +// #![no_std] if the std feature is disabled. #![cfg_attr(not(feature = "std"), no_std)] +// Export - Error and Result types. mod error; pub use error::*; diff --git a/implementations/rust/ockam/ockam_node/Cargo.lock b/implementations/rust/ockam/ockam_node/Cargo.lock index 1030e39190d..b0e17627eeb 100644 --- a/implementations/rust/ockam/ockam_node/Cargo.lock +++ b/implementations/rust/ockam/ockam_node/Cargo.lock @@ -131,7 +131,7 @@ dependencies = [ [[package]] name = "ockam_core" -version = "0.0.0" +version = "0.1.0" [[package]] name = "ockam_node" diff --git a/implementations/rust/ockam/ockam_vault/Cargo.lock b/implementations/rust/ockam/ockam_vault/Cargo.lock index a19a69053bd..aa32d62babf 100644 --- a/implementations/rust/ockam/ockam_vault/Cargo.lock +++ b/implementations/rust/ockam/ockam_vault/Cargo.lock @@ -158,7 +158,7 @@ checksum = "1cca32fa0182e8c0989459524dc356b8f2b5c10f1b9eb521b7d182c03cf8c5ff" [[package]] name = "ockam_core" -version = "0.0.0" +version = "0.1.0" [[package]] name = "ockam_core_macros" diff --git a/implementations/rust/ockam/ockam_vault_core/Cargo.lock b/implementations/rust/ockam/ockam_vault_core/Cargo.lock index bffff8a580f..b87f2fde344 100644 --- a/implementations/rust/ockam/ockam_vault_core/Cargo.lock +++ b/implementations/rust/ockam/ockam_vault_core/Cargo.lock @@ -8,7 +8,7 @@ checksum = "baf1de4339761588bc0619e3cbc0120ee582ebb74b53b4efbf79117bd2da40fd" [[package]] name = "ockam_core" -version = "0.0.0" +version = "0.1.0" [[package]] name = "ockam_core_macros"