# `Dagger`
[🔗](https://github.com/dagger/dagger/blob/v0.20.5/sdk/elixir/lib/dagger.ex#L1)

The [Dagger](https://dagger.io/) SDK for Elixir.

## Prerequisite

The SDK depends on `docker` and `dagger` commands, please make sure those
commands are presents on your `PATH`.

## Getting Started

Let's try this script below

    Mix.install([:dagger])

    # 1
    Application.ensure_all_started(:inets)

    # 2
    {:ok, client} = Dagger.connect()

    # 3
    {:ok, output} =
      client
      |> Dagger.Client.container()
      |> Dagger.Container.from("hexpm/elixir:1.14.4-erlang-25.3-debian-buster-20230227-slim")
      |> Dagger.Container.with_exec(["elixir", "--version"])
      |> Dagger.Container.stdout()

    IO.puts(output)

    # 4
    Dagger.close(client)

Here's what script do:

1. Start `:inets` application in order to use `:httpc` as a HTTP client.
2. Connecting to the Dagger Engine with `Dagger.connect/1`.
3. Create a new container from `hexpm/elixir:1.14.4-erlang-25.3-debian-buster-20230227-slim`
   and calling a command `elixir` with flag `--version`, get the standard
   output from latest command and printing it to standard output.
4. Close the connection.

## Accessing GraphQL API

In case you want to execute GraphQL directly, the SDK provides `Dagger.Core.Client`,
the client interface to the Dagger engine. The module provides 2 APIs for you:

1. `Dagger.Core.Client.query/2` - to execute a GraphQL query to the Dagger engine.
2. `Dagger.Core.Client.execute/2` - to execute a GraphQL query that produces by `Dagger.Core.QueryBuilder`.

By default, every object types (`Dagger.Container`, `Dagger.Directory`, etc.) has
a field `client` which is an instance of `Dagger.Core.Client`, you can use that instance
from the object type without initialize connection by yourself.

Please note that this API is an internal API, it may break from version to version. So
please use with cautions.

## GraphQL Client adapter

The SDK ship using Erlang `:httpc` as a backend by default. You can switch to `Req` by 
add `:req` as a dependency and configure HTTP client by adding this line below to your 
`config/config.exs`:

    config :dagger, client: Dagger.Core.GraphQLClient.Req

## Module support

The SDK also support Dagger Module, please see `Dagger.Mod.Object` for more
details.

# `close`

Disconnecting the client from Dagger Engine session.

# `connect`

Connecting to Dagger.

When calling this function, it try to connect in order:

1. Use session from `DAGGER_SESSION_PORT` and `DAGGER_SESSION_TOKEN` shell
   environment variables.
2. If (1) doesn't specified, it will lookup a binary defined in `_EXPERIMENTAL_DAGGER_CLI_BIN`
   and start a session.
3. Download the latest binary from Dagger and start a session.

## Options

* `:workdir` (`t:String.t/0`) - Sets the engine workdir.

* `:log_output` - The log device to write the progress. The default value is `:stderr`.

* `:connect_timeout` (`t:timeout/0`) - Sets timeout when connect to the engine. The default value is `10000`.

* `:query_timeout` (`t:timeout/0`) - Sets timeout when executing a query. The default value is `:infinity`.

# `connect!`

Similar to `connect/1` but raise exception when found an error.

# `with_connection`

Connect to Dagger Engine and close connection automatically after `fun` executed.

See `connect/1` for available options.

---

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