Merge pull request #672 from swimos/readme

Updates the top level readme.

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.

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

example_apps/example_util/src/lib.rs

@@ -18,39 +18,28 @@ use std::{
     net::SocketAddr,
 };
 
-use swimos::server::ServerHandle;
+use swimos::server::{until_termination, ServerHandle};
 use tokio::{select, sync::oneshot};
 use tracing_subscriber::{filter::LevelFilter, EnvFilter};
 
 pub async fn manage_handle(handle: ServerHandle) {
-    manage_handle_report(handle, None).await
+    until_termination(handle, None)
+        .await
+        .expect("Failed to register interrupt handler.");
 }
 pub async fn manage_handle_report(
-    mut handle: ServerHandle,
+    handle: ServerHandle,
     bound: Option<oneshot::Sender<SocketAddr>>,
 ) {
-    let mut shutdown_hook = Box::pin(async {
-        tokio::signal::ctrl_c()
-            .await
-            .expect("Failed to register interrupt handler.");
-    });
-    let print_addr = handle.bound_addr();
-
-    let maybe_addr = select! {
-        _ = &mut shutdown_hook => None,
-        maybe_addr = print_addr => maybe_addr,
-    };
-
-    if let Some(addr) = maybe_addr {
-        if let Some(tx) = bound {
+    let f = bound.map(|tx| {
+        let g: Box<dyn FnOnce(SocketAddr) + Send> = Box::new(move |addr| {
             let _ = tx.send(addr);
-        }
-        println!("Bound to: {}", addr);
-        shutdown_hook.await;
-    }
-
-    println!("Stopping server.");
-    handle.stop();
+        });
+        g
+    });
+    until_termination(handle, f)
+        .await
+        .expect("Failed to register interrupt handler.");
 }
 
 struct FormatMap<'a, K, V>(&'a HashMap<K, V>);

server/swimos_server_app/Cargo.toml

@@ -5,9 +5,10 @@ authors = ["Swim Inc. developers [email protected]"]
 edition = "2021"
 
 [features]
-default = []
+default = ["signal"]
 rocks_store = ["swimos_rocks_store"]
 trust_dns = ["swimos_runtime/trust_dns"]
+signal = ["tokio/signal"]
 
 [dependencies]
 futures = { workspace = true }

server/swimos_server_app/src/lib.rs

@@ -65,6 +65,9 @@ pub use self::{
     util::AgentExt,
 };
 
+#[cfg(feature = "signal")]
+pub use server::wait::{until_termination, RegistrationFailed};
+
 pub use error::{AmbiguousRoutes, ServerBuilderError, ServerError};
 pub use ratchet::deflate::{DeflateConfig, WindowBits};
 pub use swimos_introspection::IntrospectionConfig;

server/swimos_server_app/src/server/mod.rs

@@ -126,3 +126,56 @@ impl Server for BoxServer {
         self.0.run_box()
     }
 }
+
+#[cfg(feature = "signal")]
+pub mod wait {
+    use std::net::SocketAddr;
+
+    use tracing::debug;
+
+    use crate::ServerHandle;
+
+    use thiserror::Error;
+
+    /// Errors that can occur waiting for tha server to stop.
+    #[derive(Debug, Error, Clone, Copy)]
+    #[error("The Ctrl-C handler could not be installed.")]
+    pub struct RegistrationFailed;
+
+    /// Register a Ctrl-C handler that will stop a server instance.
+    ///
+    /// # Arguments
+    /// * `server` - The server to run.
+    /// * `bound` - If specified this will be called when the server has bound to a socket, with the address.
+    pub async fn until_termination(
+        mut handle: ServerHandle,
+        bound: Option<Box<dyn FnOnce(SocketAddr) + Send>>,
+    ) -> Result<(), RegistrationFailed> {
+        let wait_for_ctrl_c = async move {
+            let mut result = Ok(());
+            let mut shutdown_hook = Box::pin(async { tokio::signal::ctrl_c().await });
+
+            let print_addr = handle.bound_addr();
+
+            let maybe_addr = tokio::select! {
+                r = &mut shutdown_hook => {
+                    result = r;
+                    None
+                },
+                maybe_addr = print_addr => maybe_addr,
+            };
+
+            if let Some(addr) = maybe_addr {
+                if let Some(f) = bound {
+                    f(addr);
+                }
+                result = shutdown_hook.await;
+            }
+
+            debug!("Stopping server.");
+            handle.stop();
+            result
+        };
+        wait_for_ctrl_c.await.map_err(|_| RegistrationFailed)
+    }
+}

swimos/Cargo.toml

@@ -16,7 +16,7 @@ swimos_utilities = { path = "../swimos_utilities", features = ["io", "text"] }
 swimos_api = { path = "../api/swimos_api" }
 swimos_model = { path = "../api/swimos_model" }
 swimos_recon = { path = "../api/formats/swimos_recon" }
-swimos_server_app = { path = "../server/swimos_server_app", optional = true }
+swimos_server_app = { path = "../server/swimos_server_app", optional = true, features = ["signal"]}
 swimos_agent = { path = "../server/swimos_agent", optional = true }
 swimos_agent_derive = { path = "../server/swimos_agent_derive", optional = true }
 swimos_remote = { path = "../runtime/swimos_remote", optional = true}

swimos/src/lib.rs

@@ -94,8 +94,8 @@ pub mod io {
 #[cfg(feature = "server")]
 pub mod server {
     pub use swimos_server_app::{
-        BoxServer, DeflateConfig, IntrospectionConfig, RemoteConnectionsConfig, Server,
-        ServerBuilder, ServerHandle, WindowBits,
+        until_termination, BoxServer, DeflateConfig, IntrospectionConfig, RemoteConnectionsConfig,
+        Server, ServerBuilder, ServerHandle, WindowBits,
     };
 
     /// Configuration for TLS support in the server.
@@ -111,7 +111,7 @@ pub mod server {
         pub use swimos_remote::tls::TlsError;
         pub use swimos_remote::ConnectionError;
         pub use swimos_server_app::{
-            AmbiguousRoutes, ServerBuilderError, ServerError, UnresolvableRoute,
+            AmbiguousRoutes, RegistrationFailed, ServerBuilderError, ServerError, UnresolvableRoute,
         };
     }
 }