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/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.

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 = []

implementations/rust/ockam/ockam_core/DEVELOP.md

@@ -0,0 +1 @@
+../../DEVELOP.md

implementations/rust/ockam/ockam_core/LICENSE

@@ -0,0 +1 @@
+../../../../LICENSE

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

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<T> = std::result::Result<T, Error>;
 
+/// The type returned by Ockam functions.
 #[cfg(not(feature = "std"))]
-mod no_std_error;
+pub type Result<T> = core::result::Result<T, Error>;
+
+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);
+    }
+}

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::*;