Anwaydocsv0.5.3
Reference

Versions

The shared version number of the server and the clients, and the option names that every client takes.

The Anway server and the official clients share one version number. The current release is 0.5.2 for all of them. This page explains the version rule, the language versions that each client supports, and the option names that all clients share.

One version number

Since 0.5.1, the server and the official clients have the same version number. Each release of one repository is also a release of the others, with the same number, even when one of them has no change.

PackageInstall
ServerBinaries on GitHub releases, or the image ghcr.io/thadeu/anway
Rubybundle add anway
Gogo get github.com/thadeu/anway-go
Node.js and Bunpnpm add @anway/client
  • A client and a server with the same version are tested together. The client CI and release workflows run against the server release of the same version.
  • The platform gems of anway contain the server of the same version.
  • A client also works with an older server. But a feature that needs a new command, such as PUSHB, needs a server that has it.

For a pair that was tested together, use the same version for the server and the clients.

Features that need a newer server

FeatureServer
Topicsv0.3.0 or later
Bulk push (PUSHB)v0.3.2 or later
Bulk publish (PUBLISHB)v0.5.2 or later
The input contract belowv0.4.0 or later of the clients. The server does not change for it.

Language versions

The clients support only modern language versions. There is no support for old runtimes.

RepositoryContentLanguage floorPackage
anwayServerGo 1.27One binary
anway-goGo client and workerGo 1.26Module github.com/thadeu/anway-go
anway-rubyRuby client and worker, Rails integrationRuby 3.4, Rails 8.1Gem anway
anway-jsClient and worker for Node.js and BunNode 24, Bun 1.2Package @anway/client, ESM and CommonJS

Input contract

Since version 0.4.0, every client takes the same option names when an app declares or pushes a job. The client translates them to the fields of the protocol, so the server does not change.

Contract keyWire fieldNote
eventjobtypeThe name of what the job handles. In Ruby, the default is the class name. In Go and Node.js, it is the first argument of on.
queuequeueDefault default.
retryretryDefault 25 (server). 0 discards at the first failure. -1 goes to Dead at once.
reserve_forreserve_forSeconds.
backtracebacktraceLines.
atatA time to run later. For a push, not for a declaration.
unique_forcustom.unique_forSeconds.
unique_untilcustom.unique_untilsuccess or start.
expires_incustom.expires_inSeconds.
expires_atcustom.expires_atA time.
trackcustom.tracktrue sends 1.
on_deadcustom.on_dead{event, queue}. Its event goes to jobtype.
customcustomThe app's own keys only. The keys above win over a key with the same name here.
topicsOne SUBSCRIBE for each topicWith event as the job type, and the queue, retry, and reserve_for of the declaration. For a declaration, not for a push.

Names follow the style of each language: reserve_for in Ruby, reserveFor in Node.js, ReserveFor in Go. Durations are seconds in Ruby and Node.js, and time.Duration in Go.

Several option sets

A declaration can take more than one option set: repeated anway_options calls in Ruby, or more than one options argument in Go and Node.js. The sets merge in order, with the same rules in every client:

  • A single value, such as queue or retry: the last set that has it wins.
  • topics: the topics of all sets add up, in order, with no duplicates.
  • custom: the hashes merge, and a later key wins.
class WelcomeJob
  include Anway::Worker

  anway_options event: 'email.welcome', retry: 5
  anway_options topics: %w[user.created], queue: 'mailers'

  def perform(user_id)
    # ...
  end
end
defaults := anway.Options{Queue: "mail", Retry: anway.Int(3)}

job, err := anway.NewJob("email.send", []any{"a@b.com"}, defaults, anway.Options{Retry: anway.Int(10)})
const realtime: Anway.Options = { queue: 'realtime', retry: 3 };

worker.on('chat.broadcast', broadcast, realtime, { topics: ['chat.message'] });

Declare and push in each language

LanguageDeclarationPush
Rubyanway_options event:, queue:, topics:, ... in an Anway::Worker class. You can call it more than once. A subclass inherits all options except event and topics.perform_async, perform_in, perform_at, and set(...) with the same keys. Anway::Job.new(event, args, **options).
Goworker.On(event, handler, options ...Options)anway.NewJob(event, args, options ...Options)
Node.jsworker.on(event, handler, ...options)new Anway.Job(event, args, options)
  • A worker has one handler for each event. A second on for the same event is an error. For several flows on one topic, use several events, each subscribed to the topic.
  • client.subscribe and client.unsubscribe take topic, queue, and event. subscribe also takes retry and reserve_for.

On this page