@@ -48,7 +48,145 @@ pub mod http_server;
4848pub mod hyper;
4949pub mod serde;
5050
51- pub use restate_sdk_macros:: { object, service, workflow} ;
51+ /// Entry-point macro to define a Restate [Service](https://docs.restate.dev/concepts/services#services-1).
52+ ///
53+ /// ```rust,no_run
54+ /// use restate_sdk::prelude::*;
55+ ///
56+ /// #[restate_sdk::service]
57+ /// trait Greeter {
58+ /// async fn greet(name: String) -> Result<String, HandlerError>;
59+ /// }
60+ /// ```
61+ ///
62+ /// This macro accepts a `trait` as input, and generates as output:
63+ ///
64+ /// * A trait with the same name, that you should implement on your own concrete type (e.g. `struct`), e.g.:
65+ ///
66+ /// ```rust,no_run
67+ /// # use restate_sdk::prelude::*;
68+ /// # #[restate_sdk::service]
69+ /// # trait Greeter {
70+ /// # async fn greet(name: String) -> Result<String, HandlerError>;
71+ /// # }
72+ /// struct GreeterImpl;
73+ /// impl Greeter for GreeterImpl {
74+ /// async fn greet(&self, _: Context<'_>, name: String) -> Result<String, HandlerError> {
75+ /// Ok(format!("Greetings {name}"))
76+ /// }
77+ /// }
78+ /// ```
79+ ///
80+ /// This trait will additionally contain, for each handler, the appropriate [`Context`](crate::prelude::Context), to interact with Restate.
81+ ///
82+ /// * An implementation of the [`Service`](crate::service::Service) trait, to bind the service in the [`Endpoint`](crate::prelude::Endpoint) and expose it:
83+ ///
84+ /// ```rust,no_run
85+ /// # use restate_sdk::prelude::*;
86+ /// # #[restate_sdk::service]
87+ /// # trait Greeter {
88+ /// # async fn greet(name: String) -> HandlerResult<String>;
89+ /// # }
90+ /// # struct GreeterImpl;
91+ /// # impl Greeter for GreeterImpl {
92+ /// # async fn greet(&self, _: Context<'_>, name: String) -> HandlerResult<String> {
93+ /// # Ok(format!("Greetings {name}"))
94+ /// # }
95+ /// # }
96+ /// let endpoint = Endpoint::builder()
97+ /// // .serve() returns the implementation of Service used by the SDK
98+ /// // to bind your struct to the endpoint
99+ /// .bind(GreeterImpl.serve())
100+ /// .build();
101+ /// ```
102+ ///
103+ /// * A client implementation to call this service from another service, object or workflow, e.g.:
104+ ///
105+ /// ```rust,no_run
106+ /// # use restate_sdk::prelude::*;
107+ /// # #[restate_sdk::service]
108+ /// # trait Greeter {
109+ /// # async fn greet(name: String) -> HandlerResult<String>;
110+ /// # }
111+ /// # async fn example(ctx: Context<'_>) -> Result<(), TerminalError> {
112+ /// let result = ctx
113+ /// .service_client::<GreeterClient>()
114+ /// .greet("My greetings".to_string())
115+ /// .call()
116+ /// .await?;
117+ /// # Ok(())
118+ /// # }
119+ /// ```
120+ ///
121+ /// Methods of this trait can accept either no parameter, or one parameter implementing [`Deserialize`](crate::serde::Deserialize).
122+ /// The return value MUST always be a `Result`. Down the hood, the error type is always converted to [`HandlerError`](crate::prelude::HandlerError) for the SDK to distinguish between terminal and retryable errors. For more details, check the [`HandlerError`](crate::prelude::HandlerError) doc.
123+ ///
124+ /// When invoking the service through Restate, the method name should be used as handler name, that is:
125+ ///
126+ /// ```rust,no_run
127+ /// use restate_sdk::prelude::*;
128+ ///
129+ /// #[restate_sdk::service]
130+ /// trait Greeter {
131+ /// async fn my_greet(name: String) -> Result<String, HandlerError>;
132+ /// }
133+ /// ```
134+ ///
135+ /// The `Greeter/my_greet` handler be invoked sending a request to `http://<RESTATE_ENDPOINT>/Greeter/my_greet`.
136+ /// You can override the names used by Restate during registration using the `name` attribute:
137+ ///
138+ /// ```rust,no_run
139+ /// use restate_sdk::prelude::*;
140+ ///
141+ /// #[restate_sdk::service]
142+ /// #[name = "greeter"]
143+ /// trait Greeter {
144+ /// // You can invoke this handler with `http://<RESTATE_ENDPOINT>/greeter/myGreet`
145+ /// #[name = "myGreet"]
146+ /// async fn my_greet(name: String) -> Result<String, HandlerError>;
147+ /// }
148+ /// ```
149+ pub use restate_sdk_macros:: service;
150+
151+ /// Entry-point macro to define a Restate [Virtual object](https://docs.restate.dev/concepts/services#virtual-objects).
152+ ///
153+ /// For more details, check the [`service` macro](macro@crate::service) documentation.
154+ ///
155+ /// ## Shared handlers
156+ ///
157+ /// To define a shared handler, simply annotate the handler with the `#[shared]` annotation:
158+ ///
159+ /// ```rust,no_run
160+ /// use restate_sdk::prelude::*;
161+ ///
162+ /// #[restate_sdk::object]
163+ /// trait Counter {
164+ /// async fn add(val: u64) -> Result<u64, TerminalError>;
165+ /// #[shared]
166+ /// async fn get() -> Result<u64, TerminalError>;
167+ /// }
168+ /// ```
169+ pub use restate_sdk_macros:: object;
170+
171+ /// Entry-point macro to define a Restate [Workflow](https://docs.restate.dev/concepts/services#workflows).
172+ ///
173+ /// For more details, check the [`service` macro](macro@crate::service) documentation.
174+ ///
175+ /// ## Shared handlers
176+ ///
177+ /// To define a shared handler, simply annotate the handler with the `#[shared]` annotation:
178+ ///
179+ /// ```rust,no_run
180+ /// use restate_sdk::prelude::*;
181+ ///
182+ /// #[restate_sdk::workflow]
183+ /// trait Billing {
184+ /// async fn run() -> Result<u64, TerminalError>;
185+ /// #[shared]
186+ /// async fn get_status() -> Result<String, TerminalError>;
187+ /// }
188+ /// ```
189+ pub use restate_sdk_macros:: workflow;
52190
53191/// Prelude contains all the useful imports you need to get started with Restate.
54192pub mod prelude {
0 commit comments