updates (#12)

Author: epwalsh

Cargo.lock

@@ -6,6 +6,6 @@ src = "src"
 title = "Rusty Celery"
 
 [output.html]
-default-theme = "Rust"
+default-theme = "Coal"
 no-section-label = true
 git-repository-url = "https://github.com/rusty-celery/rusty-celery.github.io"

book.toml

@@ -11,6 +11,7 @@ In Python you can register tasks by dynamically importing them at runtime throug
 ```rust,no_run,noplaypen
 # #![allow(non_upper_case_globals)]
 # use exitfailure::ExitFailure;
+# use celery::TaskResult;
 # #[tokio::main]
 # async fn main() -> Result<(), ExitFailure> {
 # let my_app = celery::app!(
@@ -19,8 +20,8 @@ In Python you can register tasks by dynamically importing them at runtime throug
 #     task_routes = [],
 # );
 #[celery::task]
-fn add(x: i32, y: i32) -> i32 {
-    x + y
+fn add(x: i32, y: i32) -> TaskResult<i32> {
+    Ok(x + y)
 }
 
 my_app.register_task::<add>().await.unwrap();
@@ -32,18 +33,19 @@ my_app.register_task::<add>().await.unwrap();
 
 While Python Celery provides a CLI that you can use to run a worker, in Rust you'll have to implement your own worker binary. However this is a lot easier than it sounds. At a minimum you just need to initialize your [`Celery`](https://docs.rs/celery/*/celery/struct.Celery.html) application, define and register your tasks, and run the [`Celery::consume`](https://docs.rs/celery/*/celery/struct.Celery.html#method.consume) method within your `main` function.
 
-Note that `Celery::consume` is an `async` method though, which means you need an async runtime to execute it. Luckily this is provided by [`tokio`](https://docs.rs/tokio/*/tokio/) and is as simple as declaring your `main` function `async` and decorating it with the `tokio::main` macro.
+Note that `Celery::consume` is an `async` method, which means you need an async runtime to execute it. Luckily this is provided by [`tokio`](https://docs.rs/tokio/*/tokio/) and is as simple as declaring your `main` function `async` and decorating it with the `tokio::main` macro.
 
 Here is a complete example of a worker application:
 
 ```rust,no_run,noplaypen
 #![allow(non_upper_case_globals)]
 
+use celery::TaskResult;
 use exitfailure::ExitFailure;
 
 #[celery::task]
-fn add(x: i32, y: i32) -> i32 {
-    x + y
+fn add(x: i32, y: i32) -> TaskResult<i32> {
+    Ok(x + y)
 }
 
 #[tokio::main]

src/coming-from-python/index.md

@@ -5,12 +5,16 @@ A **task** represents a unit of work that a `Celery` app can produce or consume.
 The recommended way to define a task is by decorating a function with the [`task`](https://docs.rs/celery/*/celery/attr.task.html) attribute macro:
 
 ```rust,noplaypen
+use celery::TaskResult;
+
 #[celery::task]
-fn add(x: i32, y: i32) -> i32 {
-    x + y
+fn add(x: i32, y: i32) -> TaskResult<i32> {
+    Ok(x + y)
 }
 ```
 
+If the function has a return value the return type must be a [`TaskResult<T>`](https://docs.rs/celery/*/celery/task/type.TaskResult.html).
+
 Under the hood a task is just a struct that implements the [`Task`](https://docs.rs/celery/*/celery/task/trait.Task.html) trait. When you decorate a function with the task macro, this creates a struct and implements the `Task` trait so that [`Task::run`](https://docs.rs/celery/*/celery/task/trait.Task.html#method.run) calls the function you've defined.
 
 The macro accepts a number of [optional parameters](https://docs.rs/celery/*/celery/attr.task.html#parameters).
@@ -22,49 +26,30 @@ use tokio::time::{self, Duration};
 
 #[celery::task(name = "sleep", timeout = 5)]
 async fn delay(secs: u64) {
-    time::delay_for(Duration::from_secs(secs)).await
+    time::delay_for(Duration::from_secs(secs)).await;
 }
 ```
 
 ## Error handling
 
-When a task executes, i.e. when the `Task::run` method is called, it returns a [`Result<T, TaskError>`](https://docs.rs/celery/*/celery/task/type.TaskResult.html) where `T` is whatever type the function you define returns (like `i32` in the `add` task above, or `()` in the `delay` task). So when the `add` task executes, an `Ok(i32)` will be returned.
-
-The reason `Task::run` has to return a `Result` is so the worker executing the task can know when the task has failed. When an `Err(TaskError)` is returned, the worker considers the task failed and may send it back to the broker to be retried.
+When a task executes, i.e. when the `Task::run` method is called, it returns a [`TaskResult<T>`](https://docs.rs/celery/*/celery/task/type.TaskResult.html) which is just a `Result<T, TaskError>`. When an `Err(TaskError)` is returned, the worker considers the task failed and may send it back to the broker to be retried.
 
-A worker will generally treat certain [`TaskError`](https://docs.rs/celery/*/celery/error/enum.TaskError.html) variants differently. So when your task has points of failure, such as in the `read_some_file` example below, you'll need to coerce those possible error types to the appropriate `TaskError` variant and propogate them upwards:
+A worker treats certain [`TaskError`](https://docs.rs/celery/*/celery/error/enum.TaskError.html) variants differently. So when your task has points of failure, such as in the `read_some_file` example below, you'll need to coerce those possible error types to the appropriate `TaskError` variant and propogate them upwards:
 
 ```rust,noplaypen
-use celery::error::TaskResultExt;
+use celery::{TaskResult, TaskResultExt};
 
 #[celery::task]
-async fn read_some_file() -> String {
+async fn read_some_file() -> TaskResult<String> {
     tokio::fs::read_to_string("some_file")
         .await
-        .with_unexpected_err("File does not exist")?
+        .with_unexpected_err("File does not exist")
 }
 ```
 
 Here `tokio::fs::read_to_string("some_file").await` produces a [tokio::io::Result](`https://docs.rs/tokio/0.2.13/tokio/io/type.Result.html`), so we use the helper method `.with_unexpected_err` from the [`TaskResultExt`](https://docs.rs/celery/*/celery/error/trait.TaskResultExt.html) trait to convert this into a `TaskError::UnexpectedError` and then apply the [`?`](https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html#propagating-errors) operator to propogate it upwards.
 
-> There are two error kinds in particular that are meant as catch-alls for any other type of error that could arise in your task: [`TaskError::UnexpectedError`](https://docs.rs/celery/*/celery/error/enum.TaskError.html#variant.UnexpectedError) and [`TaskError::ExpectedError`](https://docs.rs/celery/*/celery/error/enum.TaskError.html#variant.ExpectedError). The latter should be used for errors that will occasionally happen due to factors outside of your control - such as a third party service being temporarily unavailable - while `UnexpectedError` should be reserved to indicate a bug or that a critical resource is missing.
-
-It's important to note that the return type of the `read_some_file` function is not a `Result` type. In fact, **the return type of the decorated function should never be a `Result` type.** The return type should always be the type that would result from a *successful* execution, and so your function should always return that bare type instead of an `Ok` or `Err`.
-
-If you're familiar with the `?` operator, you may be wondering how we can use this within a function that is marked as returning `String` and not `Result<String, _>`. The reason this works is because the `task` attribute macro modifies the body of function by wrapping it in `Ok({ ... })` and changing the return type to a `Result`.
-
-So in this example the `read_some_file` function is turned into something like this:
-
-```rust,noplaypen
-# use celery::error::{TaskResultExt, TaskError};
-async fn read_some_file() -> Result<String, TaskError> {
-    Ok({
-        tokio::fs::read_to_string("some_file")
-            .await
-            .with_unexpected_err("File does not exist")?
-    })
-}
-```
+There are two error kinds in particular that are meant as catch-alls for any other type of error that could arise in your task: [`TaskError::UnexpectedError`](https://docs.rs/celery/*/celery/error/enum.TaskError.html#variant.UnexpectedError) and [`TaskError::ExpectedError`](https://docs.rs/celery/*/celery/error/enum.TaskError.html#variant.ExpectedError). The latter should be used for errors that will occasionally happen due to factors outside of your control - such as a third party service being temporarily unavailable - while `UnexpectedError` should be reserved to indicate a bug or that a critical resource is missing.
 
 ## Positional vs keyword parameters
 
@@ -88,7 +73,7 @@ use tokio::time::{self, Duration};
 #[celery::task]
 async fn delay(secs: Option<u64>) {
     let secs = secs.unwrap_or(10);
-    time::delay_for(Duration::from_secs(secs)).await
+    time::delay_for(Duration::from_secs(secs)).await;
 }
 ```
 
@@ -114,7 +99,7 @@ use tokio::time::{self, Duration};
     on_success = success_callback,
 )]
 async fn sleep(secs: u64) {
-    time::delay_for(Duration::from_secs(secs)).await
+    time::delay_for(Duration::from_secs(secs)).await;
 }
 
 async fn failure_callback<T: Task>(task: &T, err: &TaskError) {
@@ -131,6 +116,6 @@ async fn success_callback<T: Task>(task: &T, _ret: &T::Returns) {
 
 ## Summary
 
-In summary, tasks are easily defined by decorating a function with the `#[celery::task]` macro. Internally the function is wrapped in a struct that implements the `Task` trait, and the return value of the function is wrapped in a `Result<T, celery::error::TaskError>`. This makes it valid to use `?` directly within your function.
+In summary, tasks are easily defined by decorating a function with the `#[celery::task]` macro. If the function returns anything the return type has to be a `TaskResult<T>`. Internally the function is wrapped in a struct that implements the `Task` trait.
 
 The quickest way to propogate expected or unexpected errors from within your task is by using `.with_expected_err("...")?` or `.with_unexpected_err("...")?`,  respectively, on the `Result`.

src/guide/defining-tasks.md

@@ -3,18 +3,21 @@
 Rusty Celery is provided as the [`celery`](https://crates.io/crates/celery) library on crates.io. To get started, add `celery` as a dependency to your project. Then you can define tasks by decorating functions with the [`task`](https://docs.rs/celery/*/celery/attr.task.html) attribute:
 
 ```rust,noplaypen
+use celery::TaskResult;
+
 #[celery::task]
-fn add(x: i32, y: i32) -> i32 {
-    x + y
+fn add(x: i32, y: i32) -> TaskResult<i32> {
+    Ok(x + y)
 }
 ```
 
 And create a [`Celery`](https://docs.rs/celery/*/celery/struct.Celery.html) app with the [`app`](https://docs.rs/celery/*/celery/macro.app.html) macro:
 
 ```rust,no_run,noplaypen
+# use celery::TaskResult;
 # #[celery::task]
-# fn add(x: i32, y: i32) -> i32 {
-#     x + y
+# fn add(x: i32, y: i32) -> TaskResult<i32> {
+#     Ok(x + y)
 # }
 let my_app = celery::app!(
     broker = AMQP { std::env::var("AMQP_ADDR").unwrap() },
@@ -27,9 +30,10 @@ The Celery app can be used as either a producer or consumer (worker). To send ta
 queue for a worker to consume, use the [`Celery::send_task`](https://docs.rs/celery/*/celery/struct.Celery.html#method.send_task) method:
 
 ```rust,no_run,noplaypen
+# use celery::TaskResult;
 # #[celery::task]
-# fn add(x: i32, y: i32) -> i32 {
-#     x + y
+# fn add(x: i32, y: i32) -> TaskResult<i32> {
+#     Ok(x + y)
 # }
 # #[tokio::main]
 # async fn main() -> Result<(), exitfailure::ExitFailure> {
@@ -47,9 +51,10 @@ And to act as worker and consume tasks sent to a queue by a producer, use the
 [`Celery::consume`](https://docs.rs/celery/*/celery/struct.Celery.html#method.consume) method:
 
 ```rust,no_run,noplaypen
+# use celery::TaskResult;
 # #[celery::task]
-# fn add(x: i32, y: i32) -> i32 {
-#     x + y
+# fn add(x: i32, y: i32) -> TaskResult<i32> {
+#     Ok(x + y)
 # }
 # #[tokio::main]
 # async fn main() -> Result<(), exitfailure::ExitFailure> {