Rust docs

Author: slinkydeveloper

README.md

@@ -1,4 +1,4 @@
-[![Documentation](https://img.shields.io/badge/doc-reference-blue)](https://docs.restate.dev)
+[![Documentation](https://img.shields.io/docsrs/restate-sdk)](https://docs.rs/restate-sdk)
 [![crates.io](https://img.shields.io/crates/v/restate_sdk.svg)](https://crates.io/crates/restate-sdk/)
 [![Examples](https://img.shields.io/badge/view-examples-blue)](https://github.com/restatedev/examples)
 [![Discord](https://img.shields.io/discord/1128210118216007792?logo=discord)](https://discord.gg/skW3AZ6uGd)

macros/src/ast.rs

@@ -8,8 +8,8 @@
 // the Business Source License, use of this software will be governed
 // by the Apache License, Version 2.0.
 
-//! Some parts copied from https://github.com/dtolnay/thiserror/blob/39aaeb00ff270a49e3c254d7b38b10e934d3c7a5/impl/src/ast.rs
-//! License Apache-2.0 or MIT
+// Some parts copied from https://github.com/dtolnay/thiserror/blob/39aaeb00ff270a49e3c254d7b38b10e934d3c7a5/impl/src/ast.rs
+// License Apache-2.0 or MIT
 
 use syn::ext::IdentExt;
 use syn::parse::{Parse, ParseStream};

macros/src/lib.rs

@@ -8,8 +8,8 @@
 // the Business Source License, use of this software will be governed
 // by the Apache License, Version 2.0.
 
-//! Some parts of this codebase were taken from https://github.com/google/tarpc/blob/b826f332312d3702667880a464e247556ad7dbfe/plugins/src/lib.rs
-//! License MIT
+// Some parts of this codebase were taken from https://github.com/google/tarpc/blob/b826f332312d3702667880a464e247556ad7dbfe/plugins/src/lib.rs
+// License MIT
 
 extern crate proc_macro;
 
@@ -22,6 +22,7 @@ use proc_macro::TokenStream;
 use quote::ToTokens;
 use syn::parse_macro_input;
 
+/// Entry-point macro to define a Restate service.
 #[proc_macro_attribute]
 pub fn service(_: TokenStream, input: TokenStream) -> TokenStream {
     let svc = parse_macro_input!(input as Service);
@@ -31,6 +32,7 @@ pub fn service(_: TokenStream, input: TokenStream) -> TokenStream {
         .into()
 }
 
+/// Entry-point macro to define a Restate object.
 #[proc_macro_attribute]
 pub fn object(_: TokenStream, input: TokenStream) -> TokenStream {
     let svc = parse_macro_input!(input as Object);
@@ -40,6 +42,7 @@ pub fn object(_: TokenStream, input: TokenStream) -> TokenStream {
         .into()
 }
 
+/// Entry-point macro to define a Restate workflow.
 #[proc_macro_attribute]
 pub fn workflow(_: TokenStream, input: TokenStream) -> TokenStream {
     let svc = parse_macro_input!(input as Workflow);

src/context/mod.rs

@@ -1,3 +1,5 @@
+//! Types exposing Restate functionalities to service handlers.
+
 use crate::endpoint::{ContextInternal, InputMetadata};
 use crate::errors::{HandlerResult, TerminalError};
 use crate::serde::{Deserialize, Serialize};
@@ -11,6 +13,7 @@ pub use request::{Request, RequestTarget};
 pub use run::RunClosure;
 pub type HeaderMap = http::HeaderMap<String>;
 
+/// Service handler context.
 pub struct Context<'ctx> {
     random_seed: u64,
     #[cfg(feature = "rand")]
@@ -20,10 +23,12 @@ pub struct Context<'ctx> {
 }
 
 impl<'ctx> Context<'ctx> {
+    /// Get request headers.
     pub fn headers(&self) -> &HeaderMap {
         &self.headers
     }
 
+    /// Get request headers.
     pub fn headers_mut(&mut self) -> &HeaderMap {
         &mut self.headers
     }
@@ -41,6 +46,7 @@ impl<'ctx> From<(&'ctx ContextInternal, InputMetadata)> for Context<'ctx> {
     }
 }
 
+/// Object shared handler context.
 pub struct SharedObjectContext<'ctx> {
     key: String,
     random_seed: u64,
@@ -51,14 +57,17 @@ pub struct SharedObjectContext<'ctx> {
 }
 
 impl<'ctx> SharedObjectContext<'ctx> {
+    /// Get object key.
     pub fn key(&self) -> &str {
         &self.key
     }
 
+    /// Get request headers.
     pub fn headers(&self) -> &HeaderMap {
         &self.headers
     }
 
+    /// Get request headers.
     pub fn headers_mut(&mut self) -> &HeaderMap {
         &mut self.headers
     }
@@ -77,6 +86,7 @@ impl<'ctx> From<(&'ctx ContextInternal, InputMetadata)> for SharedObjectContext<
     }
 }
 
+/// Object handler context.
 pub struct ObjectContext<'ctx> {
     key: String,
     random_seed: u64,
@@ -87,14 +97,17 @@ pub struct ObjectContext<'ctx> {
 }
 
 impl<'ctx> ObjectContext<'ctx> {
+    /// Get object key.
     pub fn key(&self) -> &str {
         &self.key
     }
 
+    /// Get request headers.
     pub fn headers(&self) -> &HeaderMap {
         &self.headers
     }
 
+    /// Get request headers.
     pub fn headers_mut(&mut self) -> &HeaderMap {
         &mut self.headers
     }
@@ -113,6 +126,7 @@ impl<'ctx> From<(&'ctx ContextInternal, InputMetadata)> for ObjectContext<'ctx>
     }
 }
 
+/// Workflow shared handler context.
 pub struct SharedWorkflowContext<'ctx> {
     key: String,
     random_seed: u64,
@@ -136,19 +150,23 @@ impl<'ctx> From<(&'ctx ContextInternal, InputMetadata)> for SharedWorkflowContex
 }
 
 impl<'ctx> SharedWorkflowContext<'ctx> {
+    /// Get workflow key.
     pub fn key(&self) -> &str {
         &self.key
     }
 
+    /// Get request headers.
     pub fn headers(&self) -> &HeaderMap {
         &self.headers
     }
 
+    /// Get request headers.
     pub fn headers_mut(&mut self) -> &HeaderMap {
         &mut self.headers
     }
 }
 
+/// Workflow handler context.
 pub struct WorkflowContext<'ctx> {
     key: String,
     random_seed: u64,
@@ -172,19 +190,23 @@ impl<'ctx> From<(&'ctx ContextInternal, InputMetadata)> for WorkflowContext<'ctx
 }
 
 impl<'ctx> WorkflowContext<'ctx> {
+    /// Get workflow key.
     pub fn key(&self) -> &str {
         &self.key
     }
 
+    /// Get request headers.
     pub fn headers(&self) -> &HeaderMap {
         &self.headers
     }
 
+    /// Get request headers.
     pub fn headers_mut(&mut self) -> &HeaderMap {
         &mut self.headers
     }
 }
 
+/// Trait exposing Restate timers functionalities.
 pub trait ContextTimers<'ctx>: private::SealedContext<'ctx> {
     /// Sleep using Restate
     fn sleep(&self, duration: Duration) -> impl Future<Output = Result<(), TerminalError>> + 'ctx {
@@ -194,7 +216,9 @@ pub trait ContextTimers<'ctx>: private::SealedContext<'ctx> {
 
 impl<'ctx, CTX: private::SealedContext<'ctx>> ContextTimers<'ctx> for CTX {}
 
+/// Trait exposing Restate service to service communication functionalities.
 pub trait ContextClient<'ctx>: private::SealedContext<'ctx> {
+    /// Create a [`Request`].
     fn request<Req, Res>(
         &self,
         request_target: RequestTarget,
@@ -203,20 +227,95 @@ pub trait ContextClient<'ctx>: private::SealedContext<'ctx> {
         Request::new(self.inner_context(), request_target, req)
     }
 
+    /// Create a service client. The service client is generated by the [`restate_sdk_macros::service`] macro with the same name of the trait suffixed with `Client`.
+    ///
+    /// ```rust
+    /// # use std::time::Duration;
+    /// # use restate_sdk::prelude::*;
+    ///
+    /// #[restate_sdk::service]
+    /// trait MyService {
+    ///   fn handle() -> HandlerResult<()>;
+    /// }
+    ///
+    /// # async fn handler(ctx: Context<'_>) {
+    ///     let client = ctx.service_client::<MyServiceClient>();
+    ///
+    ///     // Do request
+    ///     let result = client.handle().call().await;
+    ///
+    ///     // Just send the request, don't wait the response
+    ///     client.handle().send();
+    ///
+    ///     // Schedule the request to be executed later
+    ///     client.handle().send_with_delay(Duration::from_secs(60));
+    /// }
+    ///
+    /// ```
     fn service_client<C>(&self) -> C
     where
         C: IntoServiceClient<'ctx>,
     {
         C::create_client(self.inner_context())
     }
 
+    /// Create an object client. The object client is generated by the [`restate_sdk_macros::object`] macro with the same name of the trait suffixed with `Client`.
+    ///
+    /// ```rust
+    /// # use std::time::Duration;
+    /// # use restate_sdk::prelude::*;
+    ///
+    /// #[restate_sdk::object]
+    /// trait MyObject {
+    ///   fn handle() -> HandlerResult<()>;
+    /// }
+    ///
+    /// # async fn handler(ctx: Context<'_>) {
+    ///     let client = ctx.object_client::<MyObjectClient>("my-key");
+    ///
+    ///     // Do request
+    ///     let result = client.handle().call().await;
+    ///
+    ///     // Just send the request, don't wait the response
+    ///     client.handle().send();
+    ///
+    ///     // Schedule the request to be executed later
+    ///     client.handle().send_with_delay(Duration::from_secs(60));
+    /// }
+    ///
+    /// ```
     fn object_client<C>(&self, key: impl Into<String>) -> C
     where
         C: IntoObjectClient<'ctx>,
     {
         C::create_client(self.inner_context(), key.into())
     }
 
+    /// Create an workflow client. The workflow client is generated by the [`restate_sdk_macros::workflow`] macro with the same name of the trait suffixed with `Client`.
+    ///
+    /// ```rust
+    /// # use std::time::Duration;
+    /// # use restate_sdk::prelude::*;
+    ///
+    /// #[restate_sdk::workflow]
+    /// trait MyWorkflow {
+    ///   fn handle() -> HandlerResult<()>;
+    /// }
+    ///
+    /// # async fn handler(ctx: Context<'_>) {
+    ///     let client = ctx.workflow_client::<MyWorkflowClient>("my-key");
+    ///
+    ///     // Do request
+    ///     let result = client.handle().call().await;
+    ///
+    ///     // Just send the request, don't wait the response
+    ///     client.handle().send();
+    ///
+    ///     // Schedule the request to be executed later
+    ///     client.handle().send_with_delay(Duration::from_secs(60));
+    /// }
+    ///
+    /// ```
     fn workflow_client<C>(&self, key: impl Into<String>) -> C
     where
         C: IntoWorkflowClient<'ctx>,
@@ -225,20 +324,29 @@ pub trait ContextClient<'ctx>: private::SealedContext<'ctx> {
     }
 }
 
+/// Trait used by codegen to create the service client.
 pub trait IntoServiceClient<'ctx>: Sized {
     fn create_client(ctx: &'ctx ContextInternal) -> Self;
 }
 
+/// Trait used by codegen to use the object client.
 pub trait IntoObjectClient<'ctx>: Sized {
     fn create_client(ctx: &'ctx ContextInternal, key: String) -> Self;
 }
 
+/// Trait used by codegen to use the workflow client.
 pub trait IntoWorkflowClient<'ctx>: Sized {
     fn create_client(ctx: &'ctx ContextInternal, key: String) -> Self;
 }
 
 impl<'ctx, CTX: private::SealedContext<'ctx>> ContextClient<'ctx> for CTX {}
 
+/// Trait exposing Restate awakeables functionalities.
+///
+/// Awakeables can be used to implement external asynchronous systems interactions,
+/// for example you can send a Kafka record including the awakeable id returned by [`ContextAwakeables::awakeable`],
+/// and then let another service consume from Kafka the responses of given external system interaction by using
+/// [`ContextAwakeables::resolve_awakeable`] or [`ContextAwakeables::reject_awakeable`].
 pub trait ContextAwakeables<'ctx>: private::SealedContext<'ctx> {
     /// Create an awakeable
     fn awakeable<T: Deserialize + 'static>(
@@ -263,8 +371,10 @@ pub trait ContextAwakeables<'ctx>: private::SealedContext<'ctx> {
 
 impl<'ctx, CTX: private::SealedContext<'ctx>> ContextAwakeables<'ctx> for CTX {}
 
+/// Trait exposing Restate functionalities to deal with non-deterministic operations.
 pub trait ContextSideEffects<'ctx>: private::SealedContext<'ctx> {
-    /// Run a non-deterministic operation
+    /// Run a non-deterministic operation and record its result.
+    ///
     fn run<R, F, T>(
         &self,
         name: &'ctx str,
@@ -278,15 +388,23 @@ pub trait ContextSideEffects<'ctx>: private::SealedContext<'ctx> {
         self.inner_context().run(name, run_closure)
     }
 
+    /// Return a random seed inherently predictable, based on the invocation id, which is not secret.
+    ///
+    /// This value is stable during the invocation lifecycle, thus across retries.
     fn random_seed(&self) -> u64 {
         private::SealedContext::random_seed(self)
     }
 
+    /// Return a [`rand::Rng`] instance inherently predictable, seeded with [`ContextSideEffects::random_seed`].
+    ///
+    /// This instance is useful to generate identifiers, idempotency keys, and for uniform sampling from a set of options.
+    /// If a cryptographically secure value is needed, please generate that externally using [`ContextSideEffects::run`].
     #[cfg(feature = "rand")]
     fn rand(&mut self) -> &mut rand::prelude::StdRng {
         private::SealedContext::rand(self)
     }
 
+    /// Return a random [`uuid::Uuid`], generated using [`ContextSideEffects::rand`].
     #[cfg(all(feature = "rand", feature = "uuid"))]
     fn rand_uuid(&mut self) -> uuid::Uuid {
         let rand = private::SealedContext::rand(self);
@@ -296,6 +414,7 @@ pub trait ContextSideEffects<'ctx>: private::SealedContext<'ctx> {
 
 impl<'ctx, CTX: private::SealedContext<'ctx>> ContextSideEffects<'ctx> for CTX {}
 
+/// Trait exposing Restate K/V read functionalities.
 pub trait ContextReadState<'ctx>: private::SealedContext<'ctx> {
     /// Get state
     fn get<T: Deserialize + 'static>(
@@ -316,6 +435,7 @@ impl<'ctx, CTX: private::SealedContext<'ctx> + private::SealedCanReadState> Cont
 {
 }
 
+/// Trait exposing Restate K/V write functionalities.
 pub trait ContextWriteState<'ctx>: private::SealedContext<'ctx> {
     /// Set state
     fn set<T: Serialize + 'static>(&self, key: &str, t: T) {
@@ -338,6 +458,13 @@ impl<'ctx, CTX: private::SealedContext<'ctx> + private::SealedCanWriteState> Con
 {
 }
 
+/// Trait exposing Restate promise functionalities.
+///
+/// A promise is a durable, distributed version of a Rust oneshot channel.
+/// Restate keeps track of the promises across restarts/failures.
+///
+/// You can use this feature to implement interaction between different workflow handlers, e.g. to
+/// send a signal from a shared handler to the workflow handler.
 pub trait ContextPromises<'ctx>: private::SealedContext<'ctx> {
     /// Create a promise
     fn promise<T: Deserialize + 'static>(