Anwaydocsv0.5.3
Reference

Protocol

The wire protocol of the Anway server, for client authors.

Read this page to write an Anway client in a new language, or to debug a connection. The protocol follows the public Faktory work protocol, version 2, and adds new commands and optional fields. The full spec is docs/dev/protocol.md in the server repository.

A short session

S: +HI {"v":2}
C: HELLO {"v":2,"hostname":"mac.local","wid":"4f1c9a","pid":4242,"labels":["go"],"concurrency":10,"queues":["default"]}
S: +OK
C: PUSH {"jid":"a1b2c3","jobtype":"email.send","args":["a@b.com"],"queue":"default"}
S: +OK
C: FETCH default
S: $<length>
S: {"jid":"a1b2c3","jobtype":"email.send","args":["a@b.com"],"queue":"default",...}
C: ACK {"jid":"a1b2c3"}
S: +OK
C: END
S: +OK

Transport

  • TCP. The default port is 7419. Use TLS for a connection over a shared network.
  • A client sends one line for each command, ended with CRLF: a verb, then optional arguments, most often JSON.
  • The server replies in Redis RESP. Text is UTF-8.
  • One command runs at a time on a connection. There is no pipelining.
  • The longest command, with its payload, is 16 MB.
  • Client URLs use tcp:// or tcp+tls://, with an optional password: tcp://:password@localhost:7419.

Handshake

  1. The server sends HI with JSON: v (the protocol version, 2). With a password, it also sends s (a salt) and i (the hash iterations).
  2. The client sends HELLO with JSON: v, and pwdhash when the server has a password.
  3. A worker also sends hostname, wid, pid, and labels. A producer that only pushes does not need them.
  4. The server replies OK, or an error for a bad version or a bad password.

pwdhash is the hex result of SHA-256 on the password plus the salt, applied i times.

Anway fields in HELLO

A worker can send these optional fields. The web console shows them, and the server uses them for autoscale.

FieldMeaning
concurrencyThe jobs that the worker runs at once, shown as threads.
tagA short name for the app or the role of the process, such as shop.
queuesThe queues that the worker fetches, in order.
autoscale{"max": n} or {"min": n, "max": n}, to start with autoscale on. min is concurrency by default.
max_concurrencyThe most threads that the worker can run, such as the size of its database pool. The server never asks for more, and lowers an autoscale max to it.

Commands

CommandArgumentReply
PUSHJob JSONOK, or an error
PUSHBA JSON array of up to 1,000 jobsA JSON object with the reason for each refused job, by jid, or {} when all are in. See Bulk push.
FETCHQueue names, separated by spacesJob JSON, or null after at most 2 seconds
ACK{"jid"}OK
FAIL{"jid","errtype","message","backtrace"}OK
BEAT{"wid","current_state","rss_kb","concurrency"}OK, or JSON with state (quiet or terminate), concurrency, or both
INFONoneServer data as JSON, with the server and faktory hashes
QUEUEPAUSE, RESUME, or REMOVE, then queue names or *OK
MUTATE{"cmd","target","filter"}OK
BATCH NEW{"parent_bid","description","success","complete"}The bid
BATCH OPENbidThe bid
BATCH COMMITbidOK
BATCH STATUSbidStatus JSON
TRACK GETjidTrack JSON
TRACK SET{"jid","percent","desc","reserve_until"}OK
PUBLISH{"topic","args","id","unique_for","custom"}{"event","jobs","duplicate"}
PUBLISHBA JSON array of up to 1,000 PUBLISH argumentsA JSON array with one {"event","jobs","duplicate","error"} for each event, in the same order. See Bulk publish.
SUBSCRIBE{"topic","queue","jobtype","retry","reserve_for"}OK
UNSUBSCRIBE{"topic","queue","jobtype"}OK
FLUSHNoneOK. It deletes all data. It is off unless the server has ALLOW_FLUSH=true.
ENDNoneOK, then the server closes the connection
  • FETCH needs a worker connection: a HELLO with a wid. With no queue names, it fetches from default.
  • ACK or FAIL for a job that is not reserved returns an error. This can occur after the reservation expired.
  • MUTATE takes cmd (kill, discard, requeue, or clear), target (retries, scheduled, or dead), and an optional filter with jobtype, jids, and regexp. regexp is a glob with * and ?, matched against the job JSON.

Errors

ReplyWhen
-ERR <message>The command failed, for example a bad job, a duplicate jid, or an unknown command.
-NOTUNIQUE Job not uniqueA unique lock blocks the PUSH.

Job payload

FieldRequiredDefaultNote
jidYesGlobally unique, 1 to 256 bytes. The client makes it.
jobtypeYesTells the worker what to run.
argsYesJSON array. null becomes [].
queueNodefault
reserve_forNo1800Seconds. Minimum 60.
atNoNowRFC 3339
retryNo250 discards a failed job. -1 sends it to the Dead set.
backtraceNo0Lines to keep
created_atNoServer time
customNoJSON hash
enqueued_atRead-onlySet by the server
failureRead-onlySet by the server

The server reads these custom keys: expires_at, expires_in, unique_for, unique_until, on_dead, bid, and track. It sets _bid and _cb on batch callback jobs. See Jobs.

Anway extensions

Anway adds features only as new commands and optional fields. It does not change the behavior of the existing commands, so a Faktory client works as before. See Faktory clients.

Topics

PUBLISH, PUBLISHB, SUBSCRIBE, and UNSUBSCRIBE. See Topics.

Worker threads

  1. A worker that can change its threads sends its current count in each BEAT as concurrency. A worker that does not send it never gets a change.
  2. When the wanted count differs from the reported count, the BEAT reply has {"concurrency": n}. The reply has state only for quiet or terminate, so a client that reads only state is not affected.
  3. The worker starts or stops threads. A thread that stops first finishes its job. The worker then sends a BEAT with the new count at once. The server replies OK, and does not run autoscale on a BEAT that only confirms a change.

A client must read state and concurrency apart, because a reply can have one, the other, or both.

Client rules

An Anway client follows these rules, from docs/dev/clients.md:

  • The client makes the jid and the wid.
  • The client reads the server address from ANWAY_URL.
  • quiet stops fetching. The worker stays alive and continues to beat.
  • terminate, or a local stop, gives running jobs a shutdown timeout, then cancels them, then gives a short grace time. After that, the worker fails the jobs that still run.
  • A worker does not cancel a fetch in progress, because the reply can hold a job.
  • The client passes the conformance scenarios against a real server before a release.
  • The client takes the shared option names of the input contract.

On this page