Merge branch 'client_crypto_provider' of https://github.com/swimos/swim-rust into dependabot/cargo/axum-0.7.5

Author: SirCipher

.github/workflows/ci.yml

@@ -140,5 +140,5 @@ jobs:
       - name: Upload to codecov.io
         uses: codecov/codecov-action@v4
         with:
-          token: ${{secrets.CODECOV_TOKEN}}
+          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

@@ -32,6 +32,10 @@ exclude = [
     "swimos_form_derive",
     "swimos_agent_derive",
     "macro_utilities",
+    "example_client_2_2",
+    "example_server_2_2",
+    "example_client_2_3",
+    "example_server_2_3"
 ]
 workspace = true
 avoid-cfg-tarpaulin = true

Cargo.toml

@@ -40,6 +40,8 @@ members = [
     "example_apps/join_value",
     "example_apps/aggregations",
     "example_apps/time_series",
+    "example_apps/devguide/2_2/*",
+    "example_apps/devguide/2_3/*",
 ]
 
 exclude = [
@@ -119,7 +121,7 @@ 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"
+quick-xml = "0.34.0"
 csv = "1.2"
 serde-xml-rs = "0.6"
 axum = "0.7.5"

DEVELOPMENT.md

@@ -0,0 +1,21 @@
+# SwimOS Development Guid
+
+## Dependencies
+[Formatting](https://github.com/rust-lang/rustfmt): `rustup component add rustfmt`<br>
+[Clippy](https://github.com/rust-lang/rust-clippy): `rustup component add clippy`<br>
+[Tarpaulin](https://github.com/xd009642/tarpaulin) `cargo install cargo-tarpaulin`<br>
+
+## Unit tests
+#### Basic: `cargo test`
+#### With coverage: `cargo tarpaulin --ignore-tests -o Html -t 300`
+
+## Lint
+#### Manual
+1) `cargo fmt --all -- --check`
+2) `cargo clippy --all-features --workspace --all-targets -- -D warnings`
+
+#### Automatic (before commit): 
+- Install hook: `sh ./install-commit-hook.sh`
+- Remove hook: `sh ./remove-commit-hook.sh`
+
+Note: The pre-commit hooks take a while to run all checks.

LICENSE

@@ -176,7 +176,7 @@
 
    END OF TERMS AND CONDITIONS
 
-   Copyright 2023 Swim Inc.
+   Copyright 2024 Swim Inc.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

README.md

@@ -3,11 +3,21 @@
 <a href="https://www.swimos.org"><img src="https://docs.swimos.org/readme/marlin-blue.svg" align="left"></a>
 <br><br><br><br>
 
-## ⚠️🚧 Warning: Project is still under construction 👷 🚧
+The Swim Rust SDK contains software framework for building stateful applications that can be interacted
+with via multiplexed streaming APIs. It is built on top of the [Tokio asynchronous runtime](https://tokio.rs/)
+and a Tokio runtime is required for any Swim application.
 
-This project is still in its early stages of development, meaning that it is not yet stable and is subject to frequent API changes.
+Each application consists of some number of stateful agents, each of which runs as a separate Tokio task
+and can be individually addressed by a URI. An agent may have both public and private state which can either
+be held solely in memory or, optionally, in persistent storage. The public state of the agent consists of a
+number of lanes, analogous to a field in a record. There are multiple kinds of lanes that, for example, lanes
+containing single values and those containing a map of key-value pairs.
 
-**USE AT YOUR OWN RISK!**
+The state of any lane can be observed by establishing a link to it (either from another agent instance or a
+dedicated client). A established link will push all updates to the state of that lane to the subscriber and
+will also allow the subscriber to request changes to the state (for lane kinds that support this). Links
+operate over a web-socket connection and are multiplexed, meaning that links to multiple lanes on the same
+host can share a single web-socket connection.
 
 ## Usage Guides
 
@@ -17,25 +27,85 @@ This project is still in its early stages of development, meaning that it is not
 
 ## Examples
 
-TODO
-## Development
+The following example application runs a SwimOS server that hosts a single agent route where each agent instance
+has single lane, called `lane`. Each time a changes is made to the lane, it will be printed on the console by the
+server.
+
+```rust
+use swimos::{
+    agent::{
+        agent_lifecycle::HandlerContext,
+        agent_model::AgentModel,
+        event_handler::{EventHandler, HandlerActionExt},
+        lanes::ValueLane,
+        lifecycle, AgentLaneModel,
+    },
+    route::RoutePattern,
+    server::{until_termination, Server, ServerBuilder},
+};
+
+#[tokio::main]
+pub async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    
+    // An agent route consists of the agent definition and a lifecycle.
+    let model = AgentModel::new(ExampleAgent::default, ExampleLifecycle.into_lifecycle());
+
+    let server = ServerBuilder::with_plane_name("Example Plane")
+        .set_bind_addr("127.0.0.1:8080".parse()?) // Bind the server to this address.
+        .add_route(RoutePattern::parse_str("/examples/{id}")?, model) // Register the agent we have defined.
+        .build()
+        .await?;
+
+    // Run the server until we terminate it with Ctrl-C.
+    let (task, handle) = server.run();
+    let (ctrl_c_result, server_result) = tokio::join!(until_termination(handle, None), task);
 
-### Dependencies
-[Formatting](https://github.com/rust-lang/rustfmt): `rustup component add rustfmt`<br>
-[Clippy](https://github.com/rust-lang/rust-clippy): `rustup component add clippy`<br>
-[Tarpaulin](https://github.com/xd009642/tarpaulin) `cargo install cargo-tarpaulin`<br>
+    ctrl_c_result?;
+    server_result?;
+    Ok(())
+}
 
-### Unit tests
-##### Basic: `cargo test`
-##### With coverage: `cargo tarpaulin --ignore-tests -o Html -t 300`
+// Deriving the `AgentLaneModel` trait makes this type into an agent.
+#[derive(AgentLaneModel)]
+struct ExampleAgent {
+    lane: ValueLane<i32>,
+}
 
-### Lint
-##### Manual
-1) `cargo fmt --all -- --check`
-2) `cargo clippy --all-features --workspace --all-targets -- -D warnings`
+// Any agent type can have any number of lifecycles defined for it. A lifecycle describes
+// how the agent will react to events that occur as it executes.
+#[derive(Default, Clone, Copy)]
+struct ExampleLifecycle;
 
-##### Automatic (before commit): 
-- Install hook: `sh ./install-commit-hook.sh`
-- Remove hook: `sh ./remove-commit-hook.sh`
+// The `lifecycle` macro creates an method called `into_lifecycle` for the type, using the
+// annotated event handlers methods in the block.
+#[lifecycle(ExampleAgent)]
+impl ExampleLifecycle {
+    
+    #[on_event(lane)]
+    fn lane_event(
+        &self,
+        context: HandlerContext<ExampleAgent>,
+        value: &i32,
+    ) -> impl EventHandler<ExampleAgent> {
+        let n = *value;
+        context.get_agent_uri().and_then(move |uri| {
+            context.effect(move || {
+                println!("Received value: {} for 'lane' on agent at URI: {}.", n, uri);
+            })
+        })
+    }
+
+}
+```
+
+For example, if a Swim client sends an update, with the value `5`, to the agent at the URI `/examples/name` for the 
+lane `lane`, an instance of `ExampleAgent`, using `ExampleLifecycle`, will be started by the server. The value of the 
+lane will then be set to `5` and the following will be printed on the console:
+
+```
+Received value: 5 for 'lane' on agent at URI: /examples/name.
+```
+
+## Development
 
-Note: The pre-commit hooks take a while to run all checks.
+See the [development guide](DEVELOPMENT.md).

api/formats/swimos_msgpack/src/lib.rs

@@ -1,4 +1,4 @@
-// Copyright 2015-2023 Swim Inc.
+// Copyright 2015-2024 Swim Inc.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

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

@@ -1,4 +1,4 @@
-// Copyright 2015-2023 Swim Inc.
+// Copyright 2015-2024 Swim Inc.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

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

@@ -1,4 +1,4 @@
-// Copyright 2015-2023 Swim Inc.
+// Copyright 2015-2024 Swim Inc.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.