ex_incus

defmodule ExIncus do
  @moduledoc """
  Elixir client for the [Incus](https://linuxcontainers.org/incus/) REST API.

  ## Quick start

      # Local Unix socket (default: /var/lib/incus/unix.socket)
      client = ExIncus.connect()

      # Or a remote server with TLS client certificate auth
      client =
        ExIncus.connect(
          base_url: "https://incus.example.net:8443",
          certfile: "client.crt",
          keyfile: "client.key"
        )

      # Create + start a container from images.linuxcontainers.org
      {:ok, _} = ExIncus.launch(client, "web1", "debian/12")

      {:ok, result} = ExIncus.exec(client, "web1", ["hostname"])

      {:ok, _} =
        ExIncus.push_file(client, "web1", "/etc/resolv.conf",
          "nameserver 10.140.100.1\\n", mode: 0o644)

      {:ok, _} = ExIncus.stop(client, "web1")
      {:ok, _} = ExIncus.delete_instance(client, "web1")

  This module only hosts shortcuts for the most common instance operations;
  the full API surface lives in the resource modules:

    * `ExIncus.Instances` - lifecycle, state, config/devices, exec, files
    * `ExIncus.EventListener` - live event stream (websocket), for dashboards
    * `ExIncus.Snapshots` - instance snapshots
    * `ExIncus.Networks` - networks and DHCP leases
    * `ExIncus.Profiles` - profiles
    * `ExIncus.Images` - images and aliases
    * `ExIncus.Projects` - projects
    * `ExIncus.StoragePools` / `ExIncus.StorageVolumes` - storage
    * `ExIncus.Certificates` - trust store
    * `ExIncus.Server` - server info and configuration
    * `ExIncus.Operations` - background operations
    * `ExIncus.Client` - connection handling and raw requests

  ## Conventions

  Every call takes the client first and returns `{:ok, result}` or
  `{:error, %ExIncus.Error{}}`. State-changing calls are waited on by
  default; pass `wait: false` for fire-and-forget (you get the
  `ExIncus.Operation` back) or `timeout: seconds | :infinity` to control the
  wait. Endpoints not wrapped yet are reachable via
  `ExIncus.Client.request/4`.
  """

  alias ExIncus.{Client, Images, Instances, Server}

  @doc "Builds a client. See `ExIncus.Client.new/1` for options."
  defdelegate connect(opts \\ []), to: Client, as: :new

  @doc "Fetches server information. See `ExIncus.Server.info/2`."
  defdelegate server_info(client, opts \\ []), to: Server, as: :info

  @doc "Lists instances. See `ExIncus.Instances.list/2`."
  defdelegate list_instances(client, opts \\ []), to: Instances, as: :list

  @doc "Fetches an instance. See `ExIncus.Instances.get/3`."
  defdelegate get_instance(client, name, opts \\ []), to: Instances, as: :get

  @doc "Creates an instance from a params map. See `ExIncus.Instances.create/3`."
  defdelegate create_instance(client, params, opts \\ []), to: Instances, as: :create

  @doc "Creates and starts an instance from an image. See `ExIncus.Instances.launch/4`."
  defdelegate launch(client, name, image, opts \\ []), to: Instances

  @doc "Deletes an instance. See `ExIncus.Instances.delete/3`."
  defdelegate delete_instance(client, name, opts \\ []), to: Instances, as: :delete

  @doc "Starts an instance. See `ExIncus.Instances.start/3`."
  defdelegate start(client, name, opts \\ []), to: Instances

  @doc "Stops an instance. See `ExIncus.Instances.stop/3`."
  defdelegate stop(client, name, opts \\ []), to: Instances

  @doc "Restarts an instance. See `ExIncus.Instances.restart/3`."
  defdelegate restart(client, name, opts \\ []), to: Instances

  @doc "Runs a command in an instance. See `ExIncus.Instances.exec/4`."
  defdelegate exec(client, name, command, opts \\ []), to: Instances

  @doc "Writes a file into an instance. See `ExIncus.Instances.push_file/5`."
  defdelegate push_file(client, name, path, content, opts \\ []), to: Instances

  @doc "Reads a file from an instance. See `ExIncus.Instances.pull_file/4`."
  defdelegate pull_file(client, name, path, opts \\ []), to: Instances

  @doc "Imports an image tarball from disk. See `ExIncus.Images.import_file/3`."
  defdelegate import_image(client, path, opts \\ []), to: Images, as: :import_file
end