ergon_job (ergon v0.5.0)

A fully materialised job row, plus the helpers that translate between the state text column and the atoms the state machine speaks.

job() is the shared vocabulary of the whole library: ergon_db, ergon_fsm, ergon_worker, and the ergon facade all pass these maps around, and a host's handler receives one. Build one only through from_row/1, which decodes a row projected with column_list/0.

Payload

The column is jsonb, but every job-returning statement projects it as payload::text, so the driver hands back a binary. from_row/1 decodes that into a term, mirroring the encode on the way in, so a handler sees the same shape that was enqueued rather than having to parse JSON itself.

Timestamps

scheduled_at and inserted_at are whatever pg_types decodes a timestamptz into: a {Date, Time} tuple in UTC whose seconds field carries sub-second precision as a float. There is no integer-epoch alternative; see pg_timestamp() in ergon.hrl.

Summary

Types

attempt()

job()

job_id()

job_state()

pg_null()

pg_timestamp()

Functions

column_list()

The column list, in order, that every job-returning statement must project so from_row/1 lines up with the positional row the driver returns.

from_row/1

Decode a row projected with column_list/0 into a job().

state_from_binary/1

Parse a state string, returning error for a value outside the domain.

state_to_binary/1

The text form of a job state, as stored in the database.

Types

attempt()

-nominal attempt() :: non_neg_integer().

job()

-type job() ::
          #{id := ergon_job:job_id(),
            queue := binary(),
            worker := binary(),
            payload := json:decode_value(),
            state := job_state(),
            fingerprint := binary(),
            attempt := ergon_job:attempt(),
            max_attempts := pos_integer(),
            last_error := binary() | pg_null(),
            scheduled_at := pg_timestamp(),
            inserted_at := pg_timestamp()}.

job_id()

-nominal job_id() :: non_neg_integer().

job_state()

-type job_state() :: available | executing | completed | failed | discarded.

pg_null()

-type pg_null() :: null.

pg_timestamp()

-type pg_timestamp() :: {calendar:date(), {0..23, 0..59, number()}} | infinity | '-infinity'.

Functions

column_list()

-spec column_list() -> binary().

The column list, in order, that every job-returning statement must project so from_row/1 lines up with the positional row the driver returns.

This is a contract, not a convenience: the statements in priv/queries/ spell the projection out literally, and if one of them drifts from this list the mismatch surfaces as a wrong field rather than a crash. It is worth an assertion in the test suite.

from_row/1

-spec from_row(tuple()) -> job().

Decode a row projected with column_list/0 into a job().

Rows arrive as tuples. The driver's own row() type says list() | map(), but pgo_protocol builds each row with list_to_tuple/1 unless return_rows_as_maps is set, and it is not: positional decoding against this module's single clause is what makes a projection that has drifted from column_list/0 fail loudly instead of filling the wrong fields.

state_from_binary/1

-spec state_from_binary(binary()) -> {ok, job_state()} | error.

Parse a state string, returning error for a value outside the domain.

state_to_binary/1

-spec state_to_binary(job_state()) -> binary().

The text form of a job state, as stored in the database.