Anwaydocsv0.5.3

Quickstart

Start an Anway server, push a job, and run it with a worker.

In this guide, you start one Anway server on your computer. Then you push one job and run it with a worker in Ruby, Go, or Node.js.

The job in this guide has the event email.welcome and one argument, an email address. All three languages use the same event name, so a job that one language pushes can run in a worker of another language.

Start the server

Use one of these three ways. Each one starts the server on port 7419.

docker run -d --name anway \
  -p 7419:7419 \
  -e SERVER_PASSWORD=change-me \
  -v anway-data:/data \
  ghcr.io/thadeu/anway:0.5.1

The image listens on all addresses, so it needs a password. Tell the clients the password with ANWAY_URL. Set it in each terminal where you run a client:

export ANWAY_URL=tcp://:change-me@localhost:7419

Download the archive for your platform from the GitHub release. This example is for macOS on Apple silicon:

curl -fsSLO https://github.com/thadeu/anway/releases/download/v0.5.1/anway-v0.5.1-darwin-arm64.tar.gz

tar -xzf anway-v0.5.1-darwin-arm64.tar.gz

./anway-v0.5.1-darwin-arm64/anway

The server listens on 127.0.0.1:7419 and keeps its data in ./data. On a loopback address, it needs no password. The clients use tcp://127.0.0.1:7419 when ANWAY_URL is not set.

The anway gem for your platform contains the server binary. Make a folder for the project, and add the gem:

bundle init

bundle add anway

bundle exec anway server

The server listens on 127.0.0.1:7419 and keeps its data in storage/anway. The clients use this address when ANWAY_URL is not set.

In a Rails app, bin/dev starts the server with Puma. See Ruby and Rails.

The log shows server started with the address and the data directory. Keep the server running, and open a new terminal for the next steps.

Install a client

Ruby 3.4 or later. If you started the server with the gem, use the same folder and skip this step.

bundle init

bundle add anway

Go 1.26 or later.

go mod init example.com/welcome

go get github.com/thadeu/anway-go

Node 24 or later, or Bun 1.2 or later.

pnpm add @anway/client

Push a job and run it

Declare the job in a class. event is the name that the server and the other languages see.

jobs.rb
require 'anway'

class WelcomeEmail
  include Anway::Worker

  anway_options event: 'email.welcome'

  def perform(address)
    puts "Welcome email to #{address}"
  end
end

Push one job:

push.rb
require_relative 'jobs'

WelcomeEmail.perform_async('ana@example.com')
bundle exec ruby push.rb

Start a worker. -r names the file that loads the job classes:

bundle exec anway worker -r ./jobs.rb

This program pushes one job, and then runs a worker until you press Ctrl-C.

main.go
package main

import (
	"context"
	"log"
	"os"
	"os/signal"

	anway "github.com/thadeu/anway-go"
)

func main() {
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)

	defer stop()

	client, err := anway.Open("", anway.ClientOptions{})
	if err != nil {
		log.Fatal(err)
	}

	defer client.Close()

	job, err := anway.NewJob("email.welcome", []any{"ana@example.com"})
	if err != nil {
		log.Fatal(err)
	}

	if err := client.Push(ctx, job); err != nil {
		log.Fatal(err)
	}

	worker := anway.NewWorker("", anway.WorkerOptions{})

	worker.On("email.welcome", func(ctx context.Context, job *anway.Job) error {
		var address string

		if err := job.Bind(&address); err != nil {
			return err
		}

		log.Printf("Welcome email to %s", address)

		return nil
	})

	if err := worker.Run(ctx); err != nil {
		log.Fatal(err)
	}
}
go run .

A blank URL in Open and NewWorker uses ANWAY_URL.

Push one job:

push.mjs
import Anway from '@anway/client';

const client = new Anway.Client();

await client.push(new Anway.Job('email.welcome', ['ana@example.com']));

client.close();
node push.mjs

Start a worker:

worker.mjs
import Anway from '@anway/client';

const worker = new Anway.Worker();

worker.on('email.welcome', async job => {
  const [address] = job.args;

  console.log(`Welcome email to ${address}`);
});

await worker.run();
node worker.mjs

The worker prints Welcome email to ana@example.com. It continues to run and waits for more jobs. Press Ctrl-C to stop it.

What happened

  1. The client sent the job to the server with the PUSH command. The server wrote the job to disk before it replied.
  2. The worker fetched jobs from the default queue, because the job has no other queue.
  3. The handler returned with no error, so the worker acknowledged the job and the server removed it.

If a handler raises an error, the server retries the job later. Delivery is at least once, so make each handler safe to run more than one time.

Mix languages

The server sees only the event name and the arguments. So you can push the job from Ruby and run it in the Go worker, or push it from Node.js and run it in the Ruby worker. Start the worker of one tab and push with the code of another tab.

Next steps

On this page