# `AtpClient.StarExec`
[🔗](https://github.com/jcschuster/AtpClient/blob/v0.1.7/lib/atp_client/star_exec.ex#L1)

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")

# `job_id`

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

# `pair_id`

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

# `create_job`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*