From 29459bcf601afb0eff03bfd5cd1b5fd52e0813cf Mon Sep 17 00:00:00 2001
From: Daniel Gerlag <daniel@gerlag.ca>
Date: Wed, 2 Aug 2023 17:20:56 -0700
Subject: [PATCH] readme

Signed-off-by: Daniel Gerlag <daniel@gerlag.ca>
---
 examples/actors/README.md | 33 +++++++++++++++++++++++----------
 src/server/utils.rs       |  2 +-
 2 files changed, 24 insertions(+), 11 deletions(-)

diff --git a/examples/actors/README.md b/examples/actors/README.md
index c52e61a9..18bcbb15 100644
--- a/examples/actors/README.md
+++ b/examples/actors/README.md
@@ -2,7 +2,8 @@
 
 This example demonstrates the Dapr actor framework.  To author an actor, 
 
-1. Create a struct with your custom actor methods and annotate your input and output types as serializable.  The SDK will automatically deserialize the incoming parameters from JSON and then serialize your result back to JSON.
+1. Create a struct with your custom actor methods that map to [Axum handlers](https://docs.rs/axum/latest/axum/handler/index.html), use [Axum extractors](https://docs.rs/axum/latest/axum/extract/index.html) to access the incoming request and return an [`impl IntoResponse`](https://docs.rs/axum/latest/axum/response/trait.IntoResponse.html).
+Use the `DaprJson` extractor to deserialize the request from Json coming from a Dapr sidecar.
     ```rust
     #[derive(Serialize, Deserialize)]
     pub struct MyRequest {
@@ -15,14 +16,21 @@ This example demonstrates the Dapr actor framework.  To author an actor,
     }   
 
     impl MyActor {
-        fn do_stuff(&mut self, data: MyRequest) -> Result<MyResponse, actor::ActorError> {        
+        fn do_stuff(&self, DaprJson(data): DaprJson<MyRequest>) -> Json<MyResponse> {        
             println!("doing stuff with {}", data.name);        
-            Ok(MyResponse { 
+            Json(MyResponse { 
                 available: true 
             })
         }    
     }
     ```
+
+    There are many ways to write your actor method signature, using Axum handlers, but you also have access to the actor instance via `self`.  Here is a super simple example:
+    ```rust
+    pub async fn method_2(&self) -> impl IntoResponse {
+        StatusCode::OK
+    }
+    ```
 1. Implement the `Actor` trait.  This trait exposes the following methods:
     - `on_activate` - Called when an actor is activated on a host
     - `on_deactivate` - Called when an actor is deactivated on a host
@@ -34,36 +42,41 @@ This example demonstrates the Dapr actor framework.  To author an actor,
     #[async_trait]
     impl Actor for MyActor {
         
-        async fn on_activate(&mut self) -> Result<(), ActorError> {
+        async fn on_activate(&self) -> Result<(), ActorError> {
             println!("on_activate {}", self.id);
             Ok(())
         }
 
-        async fn on_deactivate(&mut self) -> Result<(), ActorError> {
+        async fn on_deactivate(&self) -> Result<(), ActorError> {
             println!("on_deactivate");
             Ok(())
         }
     }
     ```
 
+1. Mark your actor using the `actor!` macro, this enabled methods in your `impl` block to be mapped to Axum handlers.
+    ```rust
+    dapr::actor!(MyActor);
+    ```
+
 1. An actor host requires an Http server to recieve callbacks from the Dapr sidecar.  The `DaprHttpServer` object implements this functionality and also encapsulates the actor runtime to service any hosted actors.  Use the `register_actor` method to register an actor type to be serviced, this method takes an `ActorTypeRegistration` which specifies 
-    - The actor type name
+    - The actor type name (used by Actor clients), and concrete struct
     - A factory to construct a new instance of that actor type when one is required to be activated by the runtime.  The parameters passed to the factory will be the actor type, actor ID, and a Dapr client for managing state, timers and reminders for the actor.
     - The methods that you would like to expose to external clients.
 
     ```rust
     let mut dapr_server = dapr::server::DaprHttpServer::new();
 
-    dapr_server.register_actor(ActorTypeRegistration::new("MyActor", 
-        |actor_type, id, client| Box::new(MyActor{
+    dapr_server.register_actor(ActorTypeRegistration::new::<MyActor>("MyActor", 
+        Box::new(|actor_type, id, client| Arc::new(MyActor{
             actor_type, 
             id, 
             client
-        }))
+        })))
         .register_method("do_stuff", MyActor::do_stuff)
         .register_method("do_other_stuff", MyActor::do_other_stuff));
 
-    dapr_server.start(None, None).await?;
+    dapr_server.start(None).await?;
     ```
 
 
diff --git a/src/server/utils.rs b/src/server/utils.rs
index 530458f5..8e5b9b9b 100644
--- a/src/server/utils.rs
+++ b/src/server/utils.rs
@@ -52,4 +52,4 @@ impl IntoResponse for JsonRejection {
             }
         }
     }
-}
\ No newline at end of file
+}