camunda-community-hub / zeebest

A zeebe rust client

the zeebest client

This project is no longer maintained. New maintainers are welcome.

This is an unofficial Rust client for zeebe. Zeebe is a cool workflow orchestrator for microservices. Get started by by spinning up a zeebe broker locally and deploy a workflow with:

cargo run --package zeebest --example deploy_workflow

The API

This crate offers a single Client type that comes with a plethora of methods for interacting with the zeebe gateway.

Most methods are standard zeebe operations. The worker method is a bit more interesting that the other.

Workers may activate and process jobs with a handler. A worker has a max number of concurrent jobs. The worker will do its best to only request jobs from the broker up to the maximum amount. Each job handler may complete or fail a job.

Workers currently will only poll the gateway manually, so you will need to use another system to process jobs periodically. tokio::Interval does a pretty good job of this.

let mut client = Client::new("127.0.0.1", 26500).unwrap();

let handler = move |activated_job| { 
    Ok(JobResult::Complete { variables: None })
};

let mut worker = zeebest::JobWorker::new(
    "rusty-worker".to_string(),
    "payment-service".to_string(),
    Duration::from_secs(10).as_secs() as _,
    2, // max number of concurrent jobs
    PanicOption::FailJobOnPanic,
    client,
    handler,
);

// returns a stream of job results
let job_stream = worker.activate_and_process_job();

See the individual examples for how to use the client or see the complete order-process app example for a complete solution that uses a lot of the client API.

Futures

Unlike some other zeebe clients, this client is futures-first. All methods return futures or streams. Futures must be executed on a futures runtime like tokio for anything to happen.

This crate does not have a good out-of-the-box runtime solution, so you may rely on tokio or your favorite futures runtime.

Async

This crate now supports futures 0.3 (std::future). This crate does not use async-await syntax because it needs to build in stable rust. But because everything is futures 0.3, zeebest can be used with async-await in nightly rust projects.

Zeebe Versions

This crate will attempt to release with zeebe. This library is coupled to zeebe via the gateway protobuf file. This service contract will likely only change between minor patches and I believe this crate will be easiest to use if the minor version of this crate matches zeebe.

When zeebe stabilizes to 1.0.0 this may matter less. In the mean time, use the version of zeebest that matches the minor patch version of your zeebe version e.g. 0.18.x.

Deving

Ensure protoc is in your path. Install protobufs here. Many of the examples require running a zeebe broker locally. A broker may be started easily with the zeebe docker-compose project.

Contribute?

Make an issue and start a discussion! Or just submit PRs! You probably know more about this than I do.

Attributions

This project uses the protobuf file supplied by zeebe which is licensed with the Apache 2.0 license. The license is included in the protobuf file.

This takes considerable influence from the python guide published by zeebe, the zeebe-client-node-js because javascript is awesome, and the java client for the completeness.

zeebest's Issues

create an ergnonmic sync api

I'm fond of node.js's strategy for sync and async APIs. They maintain two copies of a function: one that is sync and one that is not (async). I have not seen this pattern in Rust, but I'm sure it could be ported.

This allows a user to not worry about futures, runtime or "wait"ing. A lot of times, you just want to block, especially for simpler apps.

activate_and_process_jobs should struct with job-type

It seems more data from ActivatedJob should be returned in the activate_and_process_jobs stream. This came up when instantiating several workers in the same process. There is no way to distinguish between job results based on job-type.

bpmn validation

It would be awesome to validate bpmn documents. It may be worthy of a subcrate.

Move to Camunda Community Hub?

Hi Mackenzie, we have a new Camunda Community Hub for hosting community extension. What do you think about moving Zeebest there? It will give it some more surface area and may help in find new contributors / maintainers.

put the cpu-intensive stuff on a thread pool

Currently, each job running on a job worker will block a cooperative scheduling runtime like tokio. This could be mitigated by adopting a thread pool for the cpu intensive work.

futures cpu pool seems like a good option, and will allow the code to stay in "futures world".
https://docs.rs/futures-cpupool/0.1.8/futures_cpupool/

Upgrade to std::future::Future

std::future::Future is in Beta Rust channel and already supported on Tokio. Very soon, it will be in Stable. Should probably get ahead of this.

support serializable variables for job results

One currently must manually serialize with serde_json for the optional variables field in a job result. This is kind of annoying, especially since the other client methods don't require this.

Some helper functions could be created to help with this. Perhaps:

fn complete()
fn complete_with_variables(vars: Serialize)

find a polling runtime strategy

This crate is very low level in the sense that it provides primitives likes futures and streams. It is up to the user to piece them together on a runtime. This makes implementing a polling worker a little verbose.

Other server-like crates offer a runtime that wraps tokio or another futures runtime for easier use. This crate could use something like that.

support grpc tls

It would be great if we could have secure communication with the gateway. Unfortunately, zeebe gateway does not support this, and so this issue is blocked. Thankfully, supporting it will not be too difficult as grpc supports tls.

optimize the worker api

The worker stream could be tuned and made more readable. There may also be room to let it be more flexible for different use cases, perhaps not requiring UnwindSafe. There needs to be more tests too.

worker timeout should be type safe and more obvious

The current worker api takes an i64 of milliseconds for the timeout. it's not super obvious. Maybe take a duration instead and do the conversion. Duration may return a usize so there may need to be some additional assertions placed.

Is this project still alive?

The last change was made 4 months ago, Since then there have been some changes made on zeebe itself like error handling and other improvements. Any signs on updating the rust client as well?

explore use case for `!Sync + !UnwindSafe`

Now that #16 was closed, we have a new restriction on the job handlers which is that they can be safely unwound on panic and that they must be shareable across threads. This may be too restrictive for some applications, so it should be investigated.