AtpClient.StarExec (AtpClient v0.2.0)

Copy Markdown View Source

Client for self-hosted StarExec instances.

StarExec is primarily a web application backed by Tomcat, and its programmatic surface is the same set of URLs that the web UI talks to. This module authenticates against that surface and exposes the subset of operations needed to submit benchmarks to pre-configured solvers, poll for completion, and fetch solver output.

Assumptions

The standard StarExec deployment exposes:

  • Tomcat form-based authentication at /j_security_check with the j_username and j_password fields;
  • A JSON job endpoint at /services/jobs/{job_id};
  • Solver output at /services/jobs/pairs/{pair_id}/stdout.

All of these paths are configurable; see AtpClient.Config.

Because StarExec's job-creation form accepts a large number of fields and the exact set varies by release, create_job/3 is kept minimal and deliberately flexible — consumers pass the multipart form fields their instance expects, and this module handles authentication and session cookies around the call.

Example

iex> {:ok, session} = AtpClient.StarExec.login()
iex> {:ok, job_info} = AtpClient.StarExec.get_job(session, 1234)
iex> :ok = AtpClient.StarExec.logout(session)

Configuration

config :atp_client, :starexec,
  base_url: "https://starexec.example.org/starexec",
  username: "me",
  password: System.get_env("STAREXEC_PASS")

Summary

Types

job_id()
pair_id()

Functions

create_job(session, fields, opts \\ [])

Creates a new StarExec job. The fields map is sent as the form body and must contain everything the deployment's /secure/add/job handler expects.

get_job(session, job_id, opts \\ [])

Retrieves the JSON status of a StarExec job.

get_pair_stdout(session, pair_id, opts \\ [])

Fetches the plain stdout of a single job pair. StarExec represents each (benchmark, solver, config) tuple within a job as a "pair"; this function retrieves the raw solver output for a pair, which can then be passed to AtpClient.ResultNormalization.interpret_result/1.

login(opts \\ [])

Authenticates against the configured StarExec instance and returns a Session holding the session cookies needed for subsequent requests.

logout(session, opts \\ [])

Terminates a StarExec session. Errors during logout are returned but are usually safe to ignore.

request(session, method, path, opts \\ [])

Low-level helper: issue an HTTP request against session.base_url carrying the session cookies. Consumers can use this to reach StarExec endpoints that are not yet wrapped by this module.

wait_for_job(session, job_id, opts \\ [])

Polls get_job/3 until the returned JSON reports that the job is complete or the per-call :timeout_ms elapses.

Types

job_id()

@type job_id() :: non_neg_integer() | String.t()

pair_id()

@type pair_id() :: non_neg_integer() | String.t()

Functions

create_job(session, fields, opts \\ [])

@spec create_job(AtpClient.StarExec.Session.t(), map(), keyword()) ::
  {:ok, Req.Response.t()} | {:error, term()}

Creates a new StarExec job. The fields map is sent as the form body and must contain everything the deployment's /secure/add/job handler expects.

A typical field set includes "name", "desc", "queue", "sid" (space id), "cpuTimeout", "wallclockTimeout", "benchProcess", "traversal", plus any solver/benchmark selection fields. Refer to your StarExec instance's form for the authoritative list.

Returns the raw response so the caller can extract the redirect/location that typically contains the new job id.

get_job(session, job_id, opts \\ [])

@spec get_job(AtpClient.StarExec.Session.t(), job_id(), keyword()) ::
  {:ok, map()} | {:error, term()}

Retrieves the JSON status of a StarExec job.

get_pair_stdout(session, pair_id, opts \\ [])

@spec get_pair_stdout(AtpClient.StarExec.Session.t(), pair_id(), keyword()) ::
  {:ok, String.t()} | {:error, term()}

Fetches the plain stdout of a single job pair. StarExec represents each (benchmark, solver, config) tuple within a job as a "pair"; this function retrieves the raw solver output for a pair, which can then be passed to AtpClient.ResultNormalization.interpret_result/1.

login(opts \\ [])

@spec login(keyword()) :: {:ok, AtpClient.StarExec.Session.t()} | {:error, term()}

Authenticates against the configured StarExec instance and returns a Session holding the session cookies needed for subsequent requests.

Options

  • :base_url, :username, :password — override configuration;
  • :login_path — override the auth endpoint (default /j_security_check);
  • :request_timeout_ms.

logout(session, opts \\ [])

@spec logout(
  AtpClient.StarExec.Session.t(),
  keyword()
) :: :ok | {:error, term()}

Terminates a StarExec session. Errors during logout are returned but are usually safe to ignore.

request(session, method, path, opts \\ [])

@spec request(AtpClient.StarExec.Session.t(), atom(), String.t(), keyword()) ::
  {:ok, Req.Response.t()} | {:error, term()}

Low-level helper: issue an HTTP request against session.base_url carrying the session cookies. Consumers can use this to reach StarExec endpoints that are not yet wrapped by this module.

Supported options include anything Req.request/1 accepts, plus :request_timeout_ms which is translated to :receive_timeout.

wait_for_job(session, job_id, opts \\ [])

@spec wait_for_job(AtpClient.StarExec.Session.t(), job_id(), keyword()) ::
  {:ok, map()} | {:error, term()}

Polls get_job/3 until the returned JSON reports that the job is complete or the per-call :timeout_ms elapses.

"Complete" is defined as a completed field equal to the totalJobPairs field (or a jobComplete flag being truthy). The exact JSON shape depends on the StarExec version; if it differs on your deployment, pass a custom predicate via :complete_fun, which receives the decoded job map and returns a boolean.