Tornex.Scheduler.ExecutionUnit (Tornex v0.5.1)

An execution unit for the API used by the scheduler to fan out combined queries.

Given a set of parent Tornex.SpecQuery from the Tornex.Scheduler.QueryRegistry with the same resource and resource ID (eg user/1 for all queries against Chedburn's user), this module will merge the queries into a single Tornex.Scheduler.ExecutionUnit representing all of the queries as a single query. The Tornex.Scheduler.ExecutionUnit will act as a Tornex.SpecQuery for the purposes of performing the API call with get/1, but after the API responds with data, the Tornex.Scheduler.ExecutionUnit will split the API response for the paths requested by each parent Tornex.SpecQuery and respond to the original caller of the query.

Summary

Types

t()

Functions

get(execution_unit)

Perform an API call against an Tornex.Scheduler.ExecutionUnit and forward the API response.

merge(query, execution_unit)

Merge a Tornex.SpecQuery into a Tornex.Scheduler.ExecutionUnit.

new(opts \\ [])

Create a new Tornex.Scheduler.ExecutionUnit.

to_query(execution_unit)

Convert a Tornex.Scheduler.ExecutionUnit to a Tornex.SpecQuery.

Types

t()

@type t() :: %Tornex.Scheduler.ExecutionUnit{
  key: String.t() | nil,
  key_owner: pos_integer() | nil,
  nice: Tornex.SpecQuery.niceness() | nil,
  parameters: [Tornex.SpecQuery.parameter()],
  parents: [Tornex.SpecQuery.t()],
  paths: [module()]
}

Functions

get(execution_unit)

@spec get(execution_unit :: t()) :: term()

Perform an API call against an Tornex.Scheduler.ExecutionUnit and forward the API response.

This function will perform the API call against the paths, parameters, etc. provided by the Tornex.Scheduler.ExecutionUnit with Tornex.API.get/1 as normal. However, as there can be multiple parents for the Tornex.Scheduler.ExecutionUnit, the response needs to be forwarded to all parents.

To prevent the leakage of potentially sensitive data to other parents and to minimize the size of the API responses forwarded, the API response will be split into only the paths requested by the user. If the API response is either a Torn error or some intermediate error (such as a CloudFlare error or a networking error), the API request may be retried or the error may be forwarded to the parents.

merge(query, execution_unit)

@spec merge(query :: Tornex.SpecQuery.t(), execution_unit :: t()) :: t()

Merge a Tornex.SpecQuery into a Tornex.Scheduler.ExecutionUnit.

This function will add the paths and parameters of the Tornex.SpecQuery into those of the Tornex.Scheduler.ExecutionUnit such that a portion of the execution unit will represent the parent query. If there is no API key, API key owner, or niceness in the execution unit, those of the parent query will be added to the execution unit. If there is already a niceness in the execution unit but the parent query has a higher priority niceness, the niceness of the execution unit will be replaced with the parent query's niceness.

WARNING: It is assumed that it has already been validated that it is possible to merge the Tornex.SpecQuery into the Tornex.Scheduler.ExecutionUnit in terms of security and how the API functions.

new(opts \\ [])

@spec new(opts :: keyword()) :: t()

Create a new Tornex.Scheduler.ExecutionUnit.

See Tornex.SpecQuery.new/1 for more information.

Options

:paths - list of API paths
:parameters - list of query/path parameters
:key - API key
:key_owner - ID of the owner of the API key (default: 0)
:nice - Priority of the API call between -20 and 20 (default: 20)
:parents - List of parent Tornex.SpecQuery (default: [])

to_query(execution_unit)

@spec to_query(execution_unit :: t()) :: Tornex.SpecQuery.t()

Convert a Tornex.Scheduler.ExecutionUnit to a Tornex.SpecQuery.

When converting the query into an Tornex.Scheduler.ExecutionUnit, the API-related data such as the paths and API key stored in the struct will be used in the Tornex.SpecQuery. This converted Tornex.SpecQuery can be used as normal.