Merge branch 'main' into box_local

Author: SirCipher

Cargo.toml

@@ -124,7 +124,7 @@ serde-xml-rs = "0.6"
 axum = "0.6.20"
 hyper-staticfile = "0.9"
 httparse = "1.8"
-sha1 = "0.10"
+sha-1 = "0.10.1"
 waker-fn = "1.1.0"
 num = "0.4"
 smol_str = "0.2.0"

runtime/swimos_http/Cargo.toml

@@ -11,7 +11,7 @@ hyper = { workspace = true }
 http = { workspace = true }
 httparse = { workspace = true }
 bytes = { workspace = true }
-sha1 = { workspace = true }
+sha-1 = { workspace = true }
 base64 = { workspace = true }
 thiserror = { workspace = true }
 tokio = { workspace = true }

server/swimos_agent_derive/src/lib.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Derivation macros for the structure and lifecycle of agents.
+
 use agent_lifecycle::ImplAgentLifecycle;
 use lane_model_derive::{combine_agent_attrs, make_agent_attr_consumer, DeriveAgentLaneModel};
 use lane_projections::ProjectionsImpl;
@@ -32,6 +34,7 @@ fn default_root() -> syn::Path {
 
 const AGENT_TAG: &str = "agent";
 
+/// Derives an agent implementation of an agent from a struct that lists its lanes and stores as fields.
 #[proc_macro_derive(AgentLaneModel, attributes(agent, item))]
 pub fn derive_agent_lane_model(input: TokenStream) -> TokenStream {
     let input = parse_macro_input!(input as DeriveInput);
@@ -49,6 +52,7 @@ pub fn derive_agent_lane_model(input: TokenStream) -> TokenStream {
         .into()
 }
 
+/// Derives projection functions from a struct to its fields. This is to help make agent lifecycles less verbose.
 #[proc_macro_attribute]
 pub fn projections(attr: TokenStream, item: TokenStream) -> TokenStream {
     let attr_params = if attr.is_empty() {
@@ -70,6 +74,8 @@ pub fn projections(attr: TokenStream, item: TokenStream) -> TokenStream {
         .into()
 }
 
+/// Derives the agent lifecycle trait for type. This is applied to an `impl` block for the type and uses
+/// annotated event handlers in the block to generate the lifecycle.
 #[proc_macro_attribute]
 pub fn lifecycle(attr: TokenStream, item: TokenStream) -> TokenStream {
     let meta = parse_macro_input!(attr as AttributeArgs);

server/swimos_server_app/src/error.rs

@@ -76,20 +76,27 @@ impl Display for AmbiguousRoutes {
 
 impl Error for AmbiguousRoutes {}
 
+/// Error type returned from the server task if it encounters a non-recoverable error.
 #[derive(Debug, Error)]
 pub enum ServerError {
+    /// A network connection failed and could not be re-established.
     #[error("The server network connection failed.")]
     Networking(#[from] ConnectionError),
+    /// The storage layer encountered a fatal error restoring or persisting the state of the agents.
     #[error("Opening the store for a plane failed.")]
     Persistence(#[from] StoreError),
 }
 
+/// Error type that is returned if a server cannot be started.
 #[derive(Debug, Error)]
 pub enum ServerBuilderError {
+    /// The specified agent routes are ambiguous (contain overlaps).
     #[error("The specified agent routes are invalid: {0}")]
     BadRoutes(#[from] AmbiguousRoutes),
+    /// The persistence store specified for the server could not be opened.
     #[error("Opening the store failed: {0}")]
     Persistence(#[from] StoreError),
+    /// The server TLS configuration is invalid.
     #[error("Invalid TLS configuration/certificate: {0}")]
     Tls(#[from] TlsError),
 }

server/swimos_server_app/src/lib.rs

@@ -12,8 +12,48 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! # SwimOS Server Application
+//!
+//! This module contains the main runtime loop for the SwimOS server. A SwimOS server contains a web server
+//! that can accept incoming websocket connections, using the Warp protocol, to communicate with agents
+//! that run within the server. It will additionally accept plain HTTP connections that are targetted at
+//! HTTP lanes exposed by the agents.
+//!
+//! A server instance is created by using the [`ServerBuilder`] to configure how the server should behave. By
+//! default, a server will not host any agent routes and these must be registered by calling
+//! [`ServerBuilder::add_route`]. This crate is not sufficient, in itself, to produce a complete SwimOS application
+//!  as it does not supply any implementation of the [agent interface](swimos_api::agent::Agent).
+//!
+//! A Rust implementation of agents is provided by the `swimos_agent` crate.
+//!
+//! # Examples
+//!
+//! ```no_run
+//! use std::error::Error;
+//! use swimos_server_app::{Server, ServerBuilder};
+//!
+//! # async fn example(ctrl_c: impl std::future::Future<Output = ()>) -> Result<(), Box<dyn Error>> {
+//! let server = ServerBuilder::with_plane_name("Example Server")
+//!     .set_bind_addr("127.0.0.1:8080".parse()?)
+//!     .enable_introspection()
+//!     .with_in_memory_store()
+//!     // Register agent routes.
+//!     .build()
+//!     .await?;
+//!
+//! let (task, mut handle) = server.run();
+//! let stop = async move {
+//!     ctrl_c.await; // Provide a signal to cause the server to stop. E.g. Ctrl-C.
+//!     handle.stop();
+//! };
+//! tokio::join!(stop, task).1?;
+//! # Ok(())
+//! # }
+//! ```
+//!
+
 mod config;
-pub mod error;
+mod error;
 mod in_memory_store;
 mod plane;
 mod server;
@@ -25,11 +65,9 @@ pub use self::{
     util::AgentExt,
 };
 
-pub mod introspection {
-    pub use swimos_introspection::IntrospectionConfig;
-}
-
+pub use error::{AmbiguousRoutes, ServerBuilderError, ServerError};
 pub use ratchet::deflate::DeflateConfig;
+pub use swimos_introspection::IntrospectionConfig;
 use swimos_utilities::byte_channel::{ByteReader, ByteWriter};
 
 type Io = (ByteWriter, ByteReader);

server/swimos_server_app/src/server/builder/mod.rs

@@ -37,8 +37,8 @@ use swimos_utilities::routing::RoutePattern;
 use crate::{
     config::SwimServerConfig,
     error::ServerBuilderError,
-    introspection::IntrospectionConfig,
     plane::{PlaneBuilder, PlaneModel},
+    IntrospectionConfig,
 };
 
 use super::{

server/swimos_server_app/src/server/mod.rs

@@ -31,6 +31,8 @@ use crate::error::ServerError;
 
 use self::{error::UnresolvableRoute, runtime::StartAgentRequest};
 
+/// A handle used to interact with a running Swim server instance. This can be used to find the interface
+/// on which the server is listening, instruct the server to stop and explicitly start agents.
 pub struct ServerHandle {
     stop_trigger: Option<trigger::Sender>,
     addr: Option<SocketAddr>,