Merge branch 'main' into docs4

Author: horned-sphere

.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: ""

Cargo.toml

@@ -37,6 +37,8 @@ members = [
     "example_apps/tutorial_app",
     "example_apps/tutorial_app/model",
     "example_apps/tutorial_app/generator",
+    "example_apps/join_map",
+    "example_apps/join_value",
 ]
 
 exclude = [
@@ -63,7 +65,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"
@@ -89,15 +91,15 @@ num-bigint = "0.4"
 ratchet = { package = "ratchet_rs", version = "0.4" }
 ratchet_fixture = "0.4"
 flate2 = "1.0.22"
-bitflags = "1.3"
+bitflags = "2.5"
 rocksdb = "0.22"
 integer-encoding = "3.0.4"
 rustls = "0.20"
 webpki = "0.22"
 webpki-roots = "0.22"
 tokio-rustls = "0.23"
 rustls-pemfile = "1.0.0"
-trust-dns-resolver = "0.22.0"
+trust-dns-resolver = "0.23.2"
 clap = "4.1"
 crossbeam-queue = { version = "0.3" }
 crossbeam-channel = { version = "0.5" }
@@ -106,6 +108,23 @@ 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.31.0"
+csv = "1.2"
+serde-xml-rs = "0.6"
+axum = "0.6.20"
+hyper-staticfile = "0.9"
+httparse = "1.8"
+sha1 = "0.10"
+waker-fn = "1.1.0"
+num = "0.4"
+smol_str = "0.2.0"

api/formats/swimos_msgpack/Cargo.toml

@@ -10,8 +10,8 @@ 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_recon/Cargo.toml

@@ -16,7 +16,7 @@ swimos_utilities = { path = "../../../swimos_utilities", features = ["encoding"]
 nom = { workspace = true }
 nom_locate = { workspace = true }
 num-traits = { workspace = true }
-ryu = "1.0"
+ryu = { workspace = true }
 futures = { workspace = true }
 tokio = { workspace = true, features = ["io-util"] }
 tokio-util = { workspace = true, features = ["codec"] }

api/swimos_agent_protocol/src/ad_hoc/mod.rs

@@ -29,7 +29,7 @@ use crate::AdHocCommand;
 mod tests;
 
 #[derive(Debug, Default, Clone, Copy)]
-pub struct CommandEncoder<E> {
+struct CommandEncoder<E> {
     body_encoder: E,
 }
 

api/swimos_agent_protocol/src/lib.rs

@@ -87,7 +87,7 @@ pub mod encoding {
         };
     }
 
-    /// # The encoding used for map like lanes and stores, shared between the other protocols in this module.
+    /// The encoding used for map like lanes and stores, shared between the other protocols in this module.
     pub mod map {
         pub use crate::map::{
             MapMessageDecoder, MapMessageEncoder, MapOperationDecoder, MapOperationEncoder,
@@ -96,7 +96,7 @@ pub mod encoding {
         };
     }
 
-    /// # The protocol used by the agents to send ad hoc messages to lanes on other agents.
+    /// The protocol used by the agents to send ad hoc messages to lanes on other agents.
     ///
     /// [`crate::AdHocCommand`] messages are sent by agents to the runtime to instruct it to send an ad hoc
     /// command to an arbitrary lane endpoint.
@@ -109,10 +109,6 @@ pub mod encoding {
 
     /// # The protocol used by the runtime to communicate with stores.
     ///
-    /// TODO Non-transient lanes also implicitly contain a store. They should
-    /// ultimately use the initialization component of this protocol. Currently,
-    /// they have initialization messages built into the lane protocol.
-    ///
     /// There are two phases to the communication between the runtime and the agent.
     ///
     /// 1. Initialization
@@ -135,6 +131,11 @@ pub mod encoding {
     /// 2. The store or land sends [`crate::StoreResponse`] messages each time its state
     /// changes which are persisted by the runtime.
     pub mod store {
+
+        // TODO Non-transient lanes also implicitly contain a store. They should
+        // ultimately use the initialization component of this protocol. Currently,
+        // they have initialization messages built into the lane protocol.
+
         pub use crate::store::{
             MapStoreInitDecoder, MapStoreResponseEncoder, RawMapStoreInitDecoder,
             RawMapStoreInitEncoder, RawMapStoreResponseDecoder, RawValueStoreInitDecoder,

api/swimos_agent_protocol/src/model.rs

@@ -60,42 +60,52 @@ impl<T> LaneResponse<T> {
 /// to describe alterations to the lane.
 #[derive(Copy, Clone, Debug, PartialEq, Eq, Form)]
 pub enum MapOperation<K, V> {
+    /// Update the value associated with a key in the map (or insert an entry if they key does not exist).
     #[form(tag = "update")]
     Update {
         key: K,
         #[form(body)]
         value: V,
     },
+    /// Remove an entry from the map, by key (does nothing if there is no such entry).
     #[form(tag = "remove")]
     Remove {
         #[form(header)]
         key: K,
     },
+    /// Remove all entries in the map.
     #[form(tag = "clear")]
     Clear,
 }
 
 /// Representation of map lane messages (used to form the body of Recon messages when operating)
 /// on downlinks. This extends [`MapOperation`] with `Take` (retain the first `n` items) and `Drop`
-/// (remove the first `n` items). We never use these internally but must support them for communicating
-/// with other implementations.
+/// (remove the first `n` items).
 #[derive(Copy, Clone, Debug, PartialEq, Eq, Form, Hash)]
 pub enum MapMessage<K, V> {
+    /// Update the value associated with a key in the map (or insert an entry if they key does not exist).
     #[form(tag = "update")]
     Update {
         key: K,
         #[form(body)]
         value: V,
     },
+    /// Remove an entry from the map, by key (does nothing if there is no such entry).
     #[form(tag = "remove")]
     Remove {
         #[form(header)]
         key: K,
     },
+    /// Remove all entries in the map.
     #[form(tag = "clear")]
     Clear,
+    /// Retain only the first `n` entries in the map, the remainder are removed. The ordering
+    /// used to determine 'first' is the Recon order of the keys. If there are fewer than `n`
+    /// entries in the map, this does nothing.
     #[form(tag = "take")]
     Take(#[form(header_body)] u64),
+    /// Remove the first `n` entries in the map. The ordering used to determine 'first' is the
+    /// Recon order of the keys. If there are fewer than `n` entries in the map, it is cleared.
     #[form(tag = "drop")]
     Drop(#[form(header_body)] u64),
 }
@@ -150,7 +160,8 @@ impl<S, T> AdHocCommand<S, T> {
     /// * `command` - The body of the command message.
     /// * `overwrite_permitted` - Controls the behaviour of command handling in the case of back-pressure.
     /// If this is true, the command maybe be overwritten by a subsequent command to the same target (and so
-    /// will never be sent). If false, the command will be queued instead.
+    /// will never be sent). If false, the command will be queued instead. This is a user specifiable parameter
+    /// in the API.
     pub fn new(address: Address<S>, command: T, overwrite_permitted: bool) -> Self {
         AdHocCommand {
             address,

api/swimos_api/src/agent/lane/mod.rs

@@ -12,6 +12,9 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+#[cfg(test)]
+mod tests;
+
 use std::{
     borrow::Borrow,
     fmt::{Display, Formatter},
@@ -72,7 +75,10 @@ impl WarpLaneKind {
 
     pub fn uplink_kind(&self) -> UplinkKind {
         match self {
-            WarpLaneKind::Map | WarpLaneKind::DemandMap | WarpLaneKind::JoinMap => UplinkKind::Map,
+            WarpLaneKind::Map
+            | WarpLaneKind::DemandMap
+            | WarpLaneKind::JoinMap
+            | WarpLaneKind::JoinValue => UplinkKind::Map,
             WarpLaneKind::Supply => UplinkKind::Supply,
             WarpLaneKind::Spatial => todo!("Spatial uplinks not supported."),
             _ => UplinkKind::Value,

api/swimos_api/src/agent/lane/tests.rs

@@ -0,0 +1,36 @@
+use crate::agent::UplinkKind;
+
+use super::WarpLaneKind;
+
+// spatial lanes are omitted as they are unimplemented
+const LANE_KINDS: [WarpLaneKind; 8] = [
+    WarpLaneKind::Command,
+    WarpLaneKind::Demand,
+    WarpLaneKind::DemandMap,
+    WarpLaneKind::Map,
+    WarpLaneKind::JoinMap,
+    WarpLaneKind::JoinValue,
+    WarpLaneKind::Supply,
+    WarpLaneKind::Value,
+];
+
+#[test]
+fn uplink_kinds() {
+    for kind in LANE_KINDS {
+        let uplink_kind = kind.uplink_kind();
+        if kind.map_like() {
+            assert_eq!(uplink_kind, UplinkKind::Map);
+        } else if matches!(kind, WarpLaneKind::Supply) {
+            assert_eq!(uplink_kind, UplinkKind::Supply);
+        } else {
+            assert_eq!(uplink_kind, UplinkKind::Value)
+        }
+    }
+}
+
+// this is here for when spatial lanes are implemented as the test will no longer panic
+#[test]
+#[should_panic]
+fn spatial_uplink_kind() {
+    WarpLaneKind::Spatial.uplink_kind();
+}