Merge branch 'docs_devguide_2.2' of https://github.com/swimos/swim-rust into docs_devguide_2.3

Author: SirCipher

.github/dependabot.yml

@@ -0,0 +1,9 @@
+version: 2
+updates:
+  - package-ecosystem: "cargo"
+    open-pull-requests-limit: 10
+    directory: "/"
+    schedule:
+      interval: "daily"
+#    ignore:
+#      - dependency-name: ""

.github/workflows/ci.yml

@@ -0,0 +1,144 @@
+on:
+  pull_request:
+  push:
+    branches: main
+
+name: Continuous integration
+env:
+  latest_version: "1.78.0"
+
+jobs:
+  test:
+    name: Test
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os:
+          - windows-latest
+          - ubuntu-latest
+          - macos-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: ${{ env.latest_version }}
+      - uses: Swatinem/rust-cache@v2
+
+      - name: Install NASM for aws-lc-rs on Windows
+        if: runner.os == 'Windows'
+        uses: ilammy/setup-nasm@v1
+
+      - name: Install ninja-build tool for aws-lc-fips-sys on Windows
+        if: runner.os == 'Windows'
+        uses: seanmiddleditch/gha-setup-ninja@v5
+
+      - name: Install golang for aws-lc-fips-sys on macos
+        if: runner.os == 'MacOS'
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.22.2"
+
+      - run: cargo test --all-features --workspace --lib --tests --profile "ci"
+
+  # Check step to ensure that all targets are valid as the test step doesn't run them.
+  check:
+    name: Check
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os:
+          - windows-latest
+          - ubuntu-latest
+          - macos-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: ${{ env.latest_version }}
+
+      - name: Install NASM for aws-lc-rs on Windows
+        if: runner.os == 'Windows'
+        uses: ilammy/setup-nasm@v1
+
+      - name: Install ninja-build tool for aws-lc-fips-sys on Windows
+        if: runner.os == 'Windows'
+        uses: seanmiddleditch/gha-setup-ninja@v5
+
+      - name: Install golang for aws-lc-fips-sys on macos
+        if: runner.os == 'MacOS'
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.22.2"
+
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo check --all-features --all-targets --workspace --lib --tests --profile "ci"
+
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: ${{ env.latest_version }}
+      - uses: Swatinem/rust-cache@v2
+      - name: Build Documentation
+        run: cargo doc --lib --no-deps --all-features --workspace
+        env:
+          RUSTDOCFLAGS: --cfg docsrs -Dwarnings
+
+  fmt:
+    name: Rustfmt
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: ${{ env.latest_version }}
+          components: rustfmt
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo fmt --all -- --check
+
+  clippy:
+    name: Clippy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: ${{ env.latest_version }}
+          components: clippy
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo clippy --all-features --all-targets --workspace -- -D warnings
+
+  code_coverage:
+    name: Code Coverage
+    runs-on: ubuntu-latest
+    container:
+      image: xd009642/tarpaulin:develop-nightly
+      options: --security-opt seccomp=unconfined
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: Install Clang
+        # Required for rocksdb
+        run: apt-get update && apt-get install -y llvm llvm-dev clang
+
+      - name: Set libclang path
+        run: echo "LIBCLANG_PATH=$(llvm-config --libdir)" >> $GITHUB_ENV
+
+      - name: Generate code coverage
+        run: |
+          cargo tarpaulin
+
+      - name: Upload to codecov.io
+        uses: codecov/codecov-action@v4
+        with:
+          token: ${{secrets.CODECOV_TOKEN}}
+          fail_ci_if_error: true

.gitignore

@@ -8,4 +8,7 @@
 !/demos/**/Cargo.lock
 
 **/.DS_Store
-*.iml
+*.iml
+
+# Code coverage files
+*.profraw

.tarpaulin.toml

@@ -0,0 +1,44 @@
+[coverage]
+exclude = [
+    "example-util",
+    "console",
+    "console-views",
+    "demand-lane",
+    "demand-map-lane",
+    "value-lane",
+    "map-lane",
+    "command-lane",
+    "value-store",
+    "map-store",
+    "supply-lane",
+    "value-lane-persistence",
+    "map-lane-persistence",
+    "value-store-persistence",
+    "map-store-persistence",
+    "event-downlink",
+    "value-downlink",
+    "map-downlink",
+    "local-downlink",
+    "http-lane",
+    "transit",
+    "transit-model",
+    "tutorial-app",
+    "tutorial-app-model",
+    "tutorial-app-generator",
+    "join_map",
+    "join_value",
+    "aggregations",
+    "time_series",
+    "swimos_form_derive",
+    "swimos_agent_derive",
+    "macro_utilities",
+    "example_client_2_2",
+    "example_server_2_2"
+]
+workspace = true
+avoid-cfg-tarpaulin = true
+profile = "ci"
+ignore-tests = true
+out = ["Xml"]
+timeout = "600s"
+all-features = true

Cargo.toml

@@ -7,7 +7,6 @@ members = [
     "api/formats/swimos_*",
     "macro_utilities",
     "runtime/swimos_*",
-    "swimos_store",
     "swimos_utilities",
     "swimos_utilities/swimos_*",
     "swimos_downlink",
@@ -37,6 +36,10 @@ members = [
     "example_apps/tutorial_app",
     "example_apps/tutorial_app/model",
     "example_apps/tutorial_app/generator",
+    "example_apps/join_map",
+    "example_apps/join_value",
+    "example_apps/aggregations",
+    "example_apps/time_series",
     "example_apps/devguide/2_2/*",
     "example_apps/devguide/2_3/*",
 ]
@@ -65,7 +68,7 @@ futures-util = "0.3.25"
 parking_lot = "0.12"
 pin-project = "1.0.12"
 rand = "0.8"
-criterion = "0.4"
+criterion = "0.5.1"
 either = "1.8"
 tempdir = "0.3.7"
 slab = "0.4"
@@ -77,7 +80,7 @@ nom_locate = "4.0"
 tracing = "0.1"
 tracing-subscriber = "0.3"
 tracing-appender = "0.2"
-base64 = "0.13"
+base64 = "0.22"
 num-traits = "0.2"
 thiserror = "1.0"
 static_assertions = "1.1.0"
@@ -91,24 +94,40 @@ num-bigint = "0.4"
 ratchet = { package = "ratchet_rs", version = "0.4" }
 ratchet_fixture = "0.4"
 flate2 = "1.0.22"
-bitflags = "1.3"
-rocksdb = "0.19.0"
-integer-encoding = "3.0.4"
-rustls = "0.20"
+bitflags = "2.5"
+rocksdb = "0.22"
+integer-encoding = "4.0.0"
+rustls = "0.23.10"
 webpki = "0.22"
-webpki-roots = "0.22"
-tokio-rustls = "0.23"
-rustls-pemfile = "1.0.0"
-trust-dns-resolver = "0.22.0"
+webpki-roots = "0.26.3"
+tokio-rustls = "0.26"
+rustls-pemfile = "2.1.2"
+trust-dns-resolver = "0.23.2"
 clap = "4.1"
 crossbeam-queue = { version = "0.3" }
 crossbeam-channel = { version = "0.5" }
 hyper = "0.14"
-lazy_static = "1.4.0"
 percent-encoding = "2.1.0"
 mime = "0.3"
 serde_json = "1.0"
 serde = "1.0"
-reqwest = "0.11"
+reqwest = "0.12.4"
 convert_case = "0.6"
 frunk = "0.4"
+byteorder = "1.4"
+rmp = "0.8"
+ryu = "1.0"
+regex = "1.3.6"
+fnv = "1.0.7"
+cursive = { default-features = false, version = "0.20" }
+duration-str = "0.11.2"
+quick-xml = "0.33.0"
+csv = "1.2"
+serde-xml-rs = "0.6"
+axum = "0.6.20"
+hyper-staticfile = "0.9"
+httparse = "1.8"
+sha-1 = "0.10.1"
+waker-fn = "1.1.0"
+num = "0.4"
+smol_str = "0.2.0"

api/formats/swimos_msgpack/Cargo.toml

@@ -10,8 +10,9 @@ either = { workspace = true }
 swimos_form = { path = "../../swimos_form" }
 swimos_model = { path = "../../swimos_model" }
 bytes = { workspace = true }
-byteorder = "1.4"
-rmp = "0.8"
+byteorder = { workspace = true }
+rmp = { workspace = true }
+num-bigint = { workspace = true }
 
 [dev-dependencies]
 

api/formats/swimos_msgpack/src/lib.rs

@@ -12,13 +12,43 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! MessagePack support for Swim serialization.
+//!
+//! Provides a MessagesPack backend for the Swim serialization system. This consists of two parts:
+//!
+//! - A function [`read_from_msg_pack`] that will attempt to deserialize any type that implements
+//!  [`swimos_form::read::StructuralReadable`] from a buffer containing MessagePack data.
+//! - The type [`MsgPackInterpreter`] that implements [`swimos_form::write::StructuralWriter`]
+//! allowing any type that implements [`swimos_form::write::StructuralWritable`] to be
+//! serialized as MessagePack.
+//!
+//! # Examples
+//!
+//! ```
+//! use bytes::{BufMut, BytesMut};
+//! use swimos_form::write::StructuralWritable;
+//! use swimos_msgpack::{read_from_msg_pack, MsgPackInterpreter};
+//!
+//! let mut buffer = BytesMut::with_capacity(128);
+//! let data = vec!["first".to_owned(), "second".to_owned(), "third".to_owned()];
+//! let mut writer = (&mut buffer).writer();
+//!
+//! let interpreter = MsgPackInterpreter::new(&mut writer);
+//! assert!(data.write_with(interpreter).is_ok());
+//!
+//! let mut bytes = buffer.split().freeze();
+//! let restored = read_from_msg_pack::<Vec<String>, _>(&mut bytes);
+//!
+//! assert_eq!(restored, Ok(data));
+//! ```
+
 mod reader;
 #[cfg(test)]
 mod tests;
 mod writer;
 
 pub use reader::{read_from_msg_pack, MsgPackReadError};
-pub use writer::{MsgPackBodyInterpreter, MsgPackInterpreter, MsgPackWriteError};
+pub use writer::{MsgPackInterpreter, MsgPackWriteError};
 
 const BIG_INT_EXT: i8 = 0;
 const BIG_UINT_EXT: i8 = 1;

api/formats/swimos_msgpack/src/reader/mod.rs

@@ -19,13 +19,14 @@ use std::str::Utf8Error;
 
 use bytes::{Buf, BufMut, BytesMut};
 use either::Either;
+use num_bigint::Sign;
 use rmp::decode::{read_str_len, ValueReadError};
 use rmp::Marker;
 
-use swimos_form::structural::read::event::ReadEvent;
-use swimos_form::structural::read::recognizer::Recognizer;
-use swimos_form::structural::read::{ReadError, StructuralReadable};
-use swimos_model::bigint::{BigInt, BigUint, Sign};
+use swimos_form::read::ReadEvent;
+use swimos_form::read::Recognizer;
+use swimos_form::read::{ReadError, StructuralReadable};
+use swimos_model::{BigInt, BigUint};
 
 use crate::{BIG_INT_EXT, BIG_UINT_EXT};
 
@@ -52,6 +53,9 @@ fn feed<T, E: Into<MsgPackReadError>>(maybe: Option<Result<T, E>>) -> Result<(),
 }
 
 /// Attempt to read a [`StructuralReadable`] type from MessagePack data in a buffer.
+///
+/// # Arguments
+/// * `input` - The buffer containing the MessagePack data.
 pub fn read_from_msg_pack<T: StructuralReadable, R: Buf>(
     input: &mut R,
 ) -> Result<T, MsgPackReadError> {
@@ -179,9 +183,11 @@ where
     })
 }
 
+/// Reading MessagePack data can fail if the bytes do not constitute valid MessagePack or the buffer contains
+/// an incomplete record.
 #[derive(Debug, PartialEq)]
 pub enum MsgPackReadError {
-    /// The parsed strucuture was not valid for the target type.
+    /// The parsed structure was not valid for the target type.
     Structure(ReadError),
     /// The MessagePack data contained invalid UTF8 in a string.
     StringDecode(Utf8Error),