Threadline.Job (Threadline v1.0.0)

Carries serialized actor references and stable context keys through background-job argument maps.

actor_ref_from_args/1 decodes an ActorRef, and context_opts/2 builds options for Threadline.record_action/2.

Context is explicitly passed via serializable maps and never stored in process state, ETS, or a process dictionary. This satisfies CTX-05 and keeps helpers testable as pure functions.

Usage in a worker

def perform(%{args: args}) do
  with {:ok, actor_ref} <- Threadline.Job.actor_ref_from_args(args) do
    opts = Threadline.Job.context_opts(args)

    Threadline.record_action(:member_synced,
      [actor: actor_ref, repo: MyApp.Repo] ++ opts
    )
  end
end

Enqueue with context

Serialize actor_ref with Threadline.Semantics.ActorRef.to_map/1 under the "actor_ref" key alongside other string-key fields your worker expects.

Compile-time coupling

This module references only plain maps — no compile-time dependency on any specific job runner package. Pass the args map your worker receives into these helpers.

Summary

Types

actor_ref_error()

A failure returned while decoding an actor reference from job arguments.

actor_ref_result()

The decoded actor reference or its known decoding failure.

context_opt()

An allowed extra option for context_opts/2, including integer context ID overrides.

context_opts_result()

The record-action options returned from context_opts/2.

job_args()

A JSON-compatible job argument map with string keys.

Functions

actor_ref_from_args(arg1)

Returns the ActorRef serialized in a job argument map.

context_opts(args, extra \\ [])

Builds record_action/2 keyword opts from job args.

Types

actor_ref_error()

@type actor_ref_error() ::
  :missing_actor_ref
  | :invalid_actor_ref_map
  | :unknown_actor_type
  | :missing_actor_id

A failure returned while decoding an actor reference from job arguments.

actor_ref_result()

@type actor_ref_result() ::
  {:ok, Threadline.Semantics.ActorRef.t()} | {:error, actor_ref_error()}

The decoded actor reference or its known decoding failure.

context_opt()

@type context_opt() ::
  Threadline.record_action_opt()
  | {:correlation_id, String.t() | integer() | nil}
  | {:job_id, String.t() | integer() | nil}

An allowed extra option for context_opts/2, including integer context ID overrides.

context_opts_result()

@type context_opts_result() :: [
  Threadline.record_action_opt()
  | {:correlation_id, String.t() | nil}
  | {:job_id, String.t() | nil}
]

The record-action options returned from context_opts/2.

job_args()

@type job_args() :: Threadline.json_map()

A JSON-compatible job argument map with string keys.

Functions

actor_ref_from_args(arg1)

@spec actor_ref_from_args(job_args()) :: actor_ref_result()

Returns the ActorRef serialized in a job argument map.

Looks for an "actor_ref" key containing a map serialized by ActorRef.to_map/1.

Returns

{:ok, %ActorRef{}} — the serialized reference was valid.
{:error, :missing_actor_ref | :invalid_actor_ref_map | :unknown_actor_type | :missing_actor_id} — the arguments do not contain a valid reference.

context_opts(args, extra \\ [])

@spec context_opts(job_args(), [context_opt()]) :: context_opts_result()

Builds record_action/2 keyword opts from job args.

Extracts :correlation_id and :job_id from the args map. Integer IDs are converted to strings; strings and nil are preserved. Pass these opts (merged with :actor and :repo) to Threadline.record_action/2. Allowed values supplied in extra override the values extracted from args and integer ID overrides are converted the same way.

Options

:repo — Ecto.Repo module. Optional. Passed through to record_action/2.
:storage_schema — string. Optional. Passed through to record_action/2.
:actor — ActorRef. Optional. Passed through to record_action/2.
:actor_ref — ActorRef. Optional. Passed through to record_action/2.
:status — :ok or :error. Optional. Passed through to record_action/2.
:verb — atom or string. Optional. Passed through to record_action/2.
:category — atom or string. Optional. Passed through to record_action/2.
:reason — atom or string. Optional. Passed through to record_action/2.
:comment — string. Optional. Passed through to record_action/2.
:correlation_id — string or nil in the returned options. Optional. Read from args, then overridden by extra when supplied; integer input is converted to a string.
:request_id — string. Optional. Passed through to record_action/2.
:job_id — string or nil in the returned options. Optional. Read from args, then overridden by extra when supplied; integer input is converted to a string.

extra must be a keyword list of context_opt() values, which are the documented Threadline.record_action/2 options plus integer ID overrides. Unsupported keys, malformed IDs, non-keyword extras, and option values outside that domain raise ArgumentError.

Returns

A keyword list of record-action options.

Example

opts = Threadline.Job.context_opts(args)
Threadline.record_action(:event, [actor: actor_ref, repo: Repo] ++ opts)