@callback format_job_args(job :: Oban.Job.t()) :: iodata()

Customize the formatting of job args wherever they are displayed.

This callback allows for full over args formatting; whether for privacy, brevity, or clarity. By default, all args are preserved in table and detail views.

Examples

Redact the "email" field for only the SecretJob worker:

def format_job_args(%Oban.Job{worker: "MyApp.SecretJob", args: args}) do
  args
  |> Map.replace("email", "REDACTED")
  |> inspect(pretty: true)
end

def format_job_args(job), do: Oban.Web.Resolver.format_job_args(job)

@callback format_job_meta(job :: Oban.Job.t()) :: iodata()

Customize the formatting of job meta wherever it is displayed.

This callback behaves identically to format_job_args/1, but is used for meta.

Examples

Msk the batch_id for some secret batch jobs:

def format_job_meta(%Oban.Job{meta: %{"batch_id" => _batch} = meta}) do
  meta
  |> Map.replace("batch_id", "SECRET BATCHES")
  |> inspect(pretty: true)
end

def format_job_meta(job), do: Oban.Web.Resolver.format_job_meta(job)

@callback format_recorded(recorded :: term(), job :: Oban.Job.t()) :: iodata()

Customize the formatting of recorded output wherever it is displayed.

This callback is similar to format_job_args/1, but it accepts both the recorded binary and the job to help augment the output.

Note that you must decode the recorded binary prior to inspecting it.

Examples

Disable pretty printing and change the output width to 98 characters:

def format_recorded(recorded, _job) do
  recorded
  |> Oban.Web.Resolver.decode_recorded()
  |> inspect(pretty: false, width: 98)
end

Decode the recorded value without the :safe flag set, to allow decoding terms with unknown atoms:

def format_recorded(recorded, _job) do
  recorded
  |> Oban.Web.Resolver.decode_recorded([])
  |> inspect(pretty: false, width: 98)
end

Display job args alongside recorded output:

def format_recorded(recorded, %Oban.Job{args: args}) when is_map(recorded) do
  recorded
  |> Oban.Web.Resolver.decode_recorded()
  |> Map.put(:args, args)
  |> inspect(charlists: :as_lists, pretty: true)
end

@callback hint_query_limit(qualifier()) :: :infinity | pos_integer()

The maximum number of jobs to query for auto-complete suggestions.

The limit may be determined by qualifier, e.g. :args or :worker, to fine-tune the impact of suggestion queries. Limiting may be disabled with :infinity.

Without a callback implemented it defaults to 10,000 for all qualifiers.

Example

Increase the limit to 20k for all qualifiers:

def hint_query_limit(_qualifier), do: 20_000

Customize the limit for args and meta, falling back to 10k for everything else.

def hint_query_limit(:args), do: 5_000
def hint_query_limit(:meta), do: 2_000
def hint_query_limit(_qualifier), do: 10_000

@callback jobs_query_limit(Oban.Job.unique_state()) :: :infinity | pos_integer()

The maximum number of jobs to query when displaying jobs.

Ordering is applied after limiting the query. That means the "oldest" job displayed will always be within the filter limit. For example, with a limit of 100k jobs and 200k completed jobs, only the latest 100k are queryable and the oldest 100k are effectively invisible.

In the interest of speed, limits are only approximate.

The limit may be determined by state, e.g. :completed or :cancelled, to fine-tune query performance for larger states. Limiting may be disabled with :infinity.

Without a callback impleted, the :completed state defaults to a conservative 100k jobs and all other states are :infinite.

Example

Restrict the limit for all states:

def jobs_query_limit(_qualifier), do: 50_000

Use a conservative the limit for :completed without any limit for other states (this is the default):

def jobs_query_limit(:completed), do: 100_000
def jobs_query_limit(_state), do: :infinity

@callback resolve_access(user()) :: access()

Determine the appropriate access level for a user.

During normal operation users can modify running queues and interact with jobs through the dashboard. In some situations actions such as pausing a queue may be undesired, or even dangerous for operations.

Through this callback you can tailor precisely which actions the current user can do. The default access level is :all, which permits all users to do any action.

Returning {:forbidden, path} prevents loading the dashboard entirely and redirects the user to the provided path.

The available fine grained access controls are:

• :pause_queues
• :scale_queues
• :cancel_jobs
• :delete_jobs
• :retry_jobs

Actions which aren't listed are considered disabled.

Examples

To set the dashboard read only and prevent users from performing any actions at all:

def resolve_access(_user), do: :read_only

Forbid any user that isn't an admin and redirect them to the root:

def resolve_access(user) do
  if user.admin?, do: :all, else: {:forbidden, "/"}
end

Alternatively, you can use the resolved user to allow admins write access and keep all other users read only:

def resolve_access(user) do
  if user.admin?, do: :all, else: :read_only
end

You can also specify fine grained access for each of the possible dashboard actions.

def resolve_access(user) do
  if user.admin? do
    [cancel_jobs: true, delete_jobs: true, retry_jobs: true]
  else
    :read_only
  end
end

@callback resolve_refresh(user()) :: refresh()

Determine the initial refresh rate when the dashboard mounts.

The refresh rate controls how frequently the server pulls statistics from the database, and when data is pushed from the server. The default refresh rate is 1 second.

Possible values are: 1, 2, 5, 15 or -1 to disable refreshing.

Note that this only sets the default. Users may still choose a different refresh for themselves while viewing the dashboard and their chosen value will stick for future sessions.

Examples

Default to 5 seconds:

def resolve_refresh(_user), do: 5

@callback resolve_user(conn :: Plug.Conn.t()) :: user()

Extract the current user from a Plug.Conn when the dashboard mounts.

The extracted user is passed to all of the other callback functions, allowing you to customize the dashboard per user or role.

This callback is expected to return nil, a map or a struct. However, the resolved user is only passed to other functions in the Resolver and as part of the metadata for audit events, so you're free to use any data type you like.

Examples

Extract the user from the assigns map in a typical plug based auth setup:

def resolve_user(conn) do
  conn.assigns.current_user
end