Adds example code for dev guide 2.2

Author: SirCipher

Cargo.toml

@@ -37,6 +37,7 @@ members = [
     "example_apps/tutorial_app",
     "example_apps/tutorial_app/model",
     "example_apps/tutorial_app/generator",
+    "example_apps/devguide/2_2/*",
 ]
 
 exclude = [

client/swimos_client/src/lib.rs

@@ -21,14 +21,14 @@ use swimos_remote::ws::RatchetClient;
 use futures_util::future::BoxFuture;
 #[cfg(feature = "deflate")]
 use ratchet::deflate::{DeflateConfig, DeflateExtProvider};
+pub use runtime::RemotePath;
 use runtime::{
-    start_runtime, ClientConfig, DownlinkRuntimeError, RawHandle, RemotePath, Transport,
-    WebSocketConfig,
+    start_runtime, ClientConfig, DownlinkRuntimeError, RawHandle, Transport, WebSocketConfig,
 };
 pub use runtime::{CommandError, Commander};
 use std::sync::Arc;
-use swimos_api::downlink::DownlinkConfig;
-use swimos_downlink::lifecycle::{
+pub use swimos_api::downlink::DownlinkConfig;
+pub use swimos_downlink::lifecycle::{
     BasicMapDownlinkLifecycle, BasicValueDownlinkLifecycle, MapDownlinkLifecycle,
     ValueDownlinkLifecycle,
 };
@@ -222,7 +222,7 @@ impl ClientHandle {
     ///
     /// # Arguments
     /// * `path` - The path of the downlink top open.
-    pub fn value_downlink<L, T>(
+    pub fn value_downlink<T>(
         &self,
         path: RemotePath,
     ) -> ValueDownlinkBuilder<'_, BasicValueDownlinkLifecycle<T>> {
@@ -287,19 +287,19 @@ impl<'h, L> ValueDownlinkBuilder<'h, L> {
     }
 
     /// Sets link options for the downlink.
-    pub fn options(&mut self, options: DownlinkOptions) -> &mut Self {
+    pub fn options(mut self, options: DownlinkOptions) -> Self {
         self.options = options;
         self
     }
 
     /// Sets a new downlink runtime configuration.
-    pub fn runtime_config(&mut self, config: DownlinkRuntimeConfig) -> &mut Self {
+    pub fn runtime_config(mut self, config: DownlinkRuntimeConfig) -> Self {
         self.runtime_config = config;
         self
     }
 
     /// Sets a new downlink configuration.
-    pub fn downlink_config(&mut self, config: DownlinkConfig) -> &mut Self {
+    pub fn downlink_config(mut self, config: DownlinkConfig) -> Self {
         self.downlink_config = config;
         self
     }
@@ -333,6 +333,7 @@ impl<'h, L> ValueDownlinkBuilder<'h, L> {
     }
 }
 
+#[derive(Debug)]
 pub enum ValueDownlinkOperationError {
     NotYetSynced,
     DownlinkStopped,

example_apps/devguide/2_2/example_client/Cargo.toml

@@ -0,0 +1,9 @@
+[package]
+name = "example_client"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+tokio = { workspace = true, features = ["full"] }
+swimos_client = { path = "../../../../client/swimos_client" }
+swimos_form = { path = "../../../../api/swimos_form" }

example_apps/devguide/2_2/example_client/src/main.rs

@@ -0,0 +1,54 @@
+use swimos_client::{BasicValueDownlinkLifecycle, DownlinkConfig, RemotePath, SwimClientBuilder};
+
+#[tokio::main]
+async fn main() {
+    // Build a Swim Client using the default configuration.
+    // The `build` method returns a `SwimClient` instance and its internal
+    // runtime future that is spawned below.
+    let (client, task) = SwimClientBuilder::default().build().await;
+    let _client_task = tokio::spawn(task);
+    let handle = client.handle();
+
+    // Build a path the downlink.
+    let state_path = RemotePath::new(
+        // The host address
+        "ws://0.0.0.0:8080",
+        // You can provide any agent URI that matches the pattern
+        // "/example/:id"
+        "/example/1",
+        // This is the URI of the ValueLane<i32> in our ExampleAgent
+        "state",
+    );
+
+    let lifecycle = BasicValueDownlinkLifecycle::<usize>::default()
+        // Register an event handler that is invoked when the downlink connects to the agent.
+        .on_linked_blocking(|| println!("Downlink linked"))
+        // Register an event handler that is invoked when the downlink synchronises its state.
+        // with the agent.
+        .on_synced_blocking(|value| println!("Downlink synced with: {value:?}"))
+        // Register an event handler that is invoked when the downlink receives an event.
+        .on_event_blocking(|value| println!("Downlink event: {value:?}"));
+
+    // Build our downlink.
+    //
+    // This operation may fail if there is a connection issue.
+    let state_downlink = handle
+        .value_downlink::<i32>(state_path)
+        .lifecycle(lifecycle)
+        .downlink_config(DownlinkConfig::default())
+        .open()
+        .await
+        .expect("Failed to open downlink");
+
+    for i in 0..10 {
+        // Update the lane's state.
+        state_downlink
+            .set(i)
+            .await
+            .expect("Failed to set downlink state");
+    }
+
+    tokio::signal::ctrl_c()
+        .await
+        .expect("Failed to listen for ctrl-c.");
+}

example_apps/devguide/2_2/example_server/Cargo.toml

@@ -0,0 +1,9 @@
+[package]
+name = "example_server"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+tokio = { workspace = true, features = ["full"] }
+swimos = { path = "../../../../swimos", features = ["server"] }
+swimos_form = { path = "../../../../api/swimos_form" }

example_apps/devguide/2_2/example_server/src/main.rs

@@ -0,0 +1,103 @@
+use swimos::{
+    agent::{
+        agent_lifecycle::utility::HandlerContext, agent_model::AgentModel,
+        event_handler::EventHandler, lanes::ValueLane, lifecycle, projections, AgentLaneModel,
+    },
+    route::RoutePattern,
+    server::{Server, ServerBuilder, ServerHandle},
+};
+
+use std::{error::Error, time::Duration};
+#[derive(AgentLaneModel)]
+#[projections]
+pub struct ExampleAgent {
+    state: ValueLane<i32>,
+}
+
+#[derive(Clone)]
+pub struct ExampleLifecycle;
+
+#[lifecycle(ExampleAgent)]
+impl ExampleLifecycle {
+    // Handler invoked when the agent starts.
+    #[on_start]
+    pub fn on_start(
+        &self,
+        context: HandlerContext<ExampleAgent>,
+    ) -> impl EventHandler<ExampleAgent> {
+        context.effect(|| println!("Starting agent."))
+    }
+
+    // Handler invoked when the agent is about to stop.
+    #[on_stop]
+    pub fn on_stop(
+        &self,
+        context: HandlerContext<ExampleAgent>,
+    ) -> impl EventHandler<ExampleAgent> {
+        context.effect(|| println!("Stopping agent."))
+    }
+
+    // Handler invoked after the state of 'lane' has changed.
+    #[on_event(state)]
+    pub fn on_event(
+        &self,
+        context: HandlerContext<ExampleAgent>,
+        value: &i32,
+    ) -> impl EventHandler<ExampleAgent> {
+        let n = *value;
+        // EventHandler::effect accepts a FnOnce()
+        // which runs a side effect.
+        context.effect(move || {
+            println!("Setting value to: {}", n);
+        })
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
+    // Create a dynamic route for our agents.
+    let route = RoutePattern::parse_str("/example/:id")?;
+    // Create an agent model which contains the factory for creating the agent as well
+    // as the lifecycle which will be run.
+    let agent = AgentModel::new(ExampleAgent::default, ExampleLifecycle.into_lifecycle());
+
+    // Create a server builder.
+    let server = ServerBuilder::with_plane_name("Plane")
+        // Bind to port 8080
+        .set_bind_addr("127.0.0.1:8080".parse().unwrap())
+        // For this guide, ensure agents timeout fairly quickly.
+        // An agent will timeout after they have received no new updates
+        // for this configured period of time.
+        .update_config(|config| {
+            config.agent_runtime.inactive_timeout = Duration::from_secs(20);
+        })
+        // Register the agent against the route.
+        .add_route(route, agent)
+        .build()
+        // Building the server may fail if many routes are registered and some
+        // are ambiguous.
+        .await?;
+
+    // Run the server. A tuple of the server's runtime
+    // future and a handle to the runtime is returned.
+    let (task, handle) = server.run();
+    // Watch for ctrl+c signals
+    let shutdown = manage_handle(handle);
+
+    // Join on the server and ctrl+c futures.
+    let (_, result) = tokio::join!(shutdown, task);
+
+    result?;
+    println!("Server stopped successfully.");
+    Ok(())
+}
+
+// Utility function for awaiting a stop signal in the terminal.
+async fn manage_handle(mut handle: ServerHandle) {
+    tokio::signal::ctrl_c()
+        .await
+        .expect("Failed to register interrupt handler.");
+
+    println!("Stopping server.");
+    handle.stop();
+}