Crate faktory

API bindings for Faktory workers and job producers.

This crate provides API bindings for the language-agnostic Faktory work server. For a more detailed system overview of the work server, what jobs are, and how they are scheduled, see the Faktory docs.

System overview

At a high level, Faktory has two primary concepts: jobs and workers. Jobs are pieces of work that clients want to have executed, and workers are the things that eventually execute those jobs. A client enqueues a job, Faktory sends the job to an available worker (and waits if they’re all busy), the worker executes the job, and eventually reports back to Faktory that the job has completed.

Jobs are self-contained, and consist of a job type (a string), arguments for the job, and bits and pieces of metadata. When a job is scheduled for execution, the worker is given this information, and uses the job type to figure out how to execute the job. You can think of job execution as a remote function call (or RPC) where the job type is the name of the function, and the job arguments are, perhaps unsuprisingly, the arguments to the function.

In this crate, you will find bindings both for submitting jobs (clients that produce jobs) and for executing jobs (workers that consume jobs). The former can be done by making a Client, whereas the latter is done with a Worker. See the documentation for each for more details on how to use them.

Encrypted connections (TLS)

To connect to a Faktory server hosted over TLS, add the tls feature, and see the documentation for TlsStream, which can be supplied to Client::connect_with and WorkerBuilder::connect_with.

Examples

If you want to submit jobs to Faktory, use Client.

use faktory::{Client, Job};
let mut client = Client::connect().await.unwrap();
client.enqueue(Job::new("foobar", vec!["z"])).await.unwrap();

let (enqueued_count, errors) = client.enqueue_many([Job::new("foobar", vec!["z"]), Job::new("foobar", vec!["z"])]).await.unwrap();
assert_eq!(enqueued_count, 2);
assert_eq!(errors, None);
});

If you want to accept jobs from Faktory, use Worker.

use async_trait::async_trait;
use faktory::{Job, JobRunner, Worker};
use std::io;

struct DomainEntity(i32);

impl DomainEntity {
    fn new(buzz: i32) -> Self {
        DomainEntity(buzz)
    }
}

#[async_trait]
impl JobRunner for DomainEntity {
    type Error = io::Error;

    async fn run(&self, job: Job) -> Result<(), Self::Error> {
        println!("{:?}, buzz={}", job, self.0);
        Ok(())
    }
}

let mut w = Worker::builder()
    .register("fizz", DomainEntity::new(1))
    .register_fn("foobar", |job| async move {
        println!("{:?}", job);
        Ok::<(), io::Error>(())
    })
    .register_blocking_fn("fibo", |job| {
        std::thread::sleep(std::time::Duration::from_millis(1000));
        println!("{:?}", job);
        Ok::<(), io::Error>(())
    })
    .with_rustls() // available on `rustls` feature only
    .connect()
    .await
    .unwrap();

if let Err(e) = w.run(&["default"]).await {
    println!("worker failed: {}", e);
}

Re-exports

• pub use crate::error::Error;

Modules

• entent
  Constructs only available with the enterprise version of Faktory.
• error
  Enumerates all errors that this crate may return.
• native_tlsnative_tls
  Namespace for native TLS powered TlsStream.
• rustlsrustls
  Namespace for Rustls-powered TlsStream.

Structs

• Client
  Client is used to enqueue new jobs that will in turn be processed by Faktory workers.
• DataSnapshot
  Faktory service information.
• FaktoryState
  Current server state.
• Job
  A Faktory job.
• JobBuilder
  Builder for Job.
• JobId
  Job identifier.
• ServerSnapshot
  Faktory’s server process information.
• StopDetails
  Holds some details aroung a worker’s run stoppage, such as the reason why this worker discontinued and the number of workers that might still be processing jobs at that instant.
• Worker
  Worker is used to run a worker that processes jobs provided by Faktory.
• WorkerBuilder
  Convenience wrapper for building a Faktory worker.
• WorkerId
  Worker identifier.

Enums

• StopReason
  A reason why Worker::run has discontinued.

Traits

• Connection
  A duplex buffered stream to the Faktory service.
• JobRunner
  Implementations of this trait can be registered to run jobs in a Worker.
• Reconnect
  A stream that can be re-established after failing.