Introduce Tesla.client/1 & Tesla.client/2

README.md

@@ -121,7 +121,7 @@ Consider the following case: GitHub API can be accessed using OAuth token author
 We can't use `plug Tesla.Middleware.Headers, [{"authorization", "token here"}]`
 since this would be compiled only once and there is no way to insert dynamic user token.
 
-Instead, we can use `Tesla.build_client` to create a dynamic middleware function:
+Instead, we can use `Tesla.client` to create a dynamic middleware function:
 
 ```elixir
 defmodule GitHub do
@@ -139,9 +139,9 @@ defmodule GitHub do
 
   # build dynamic client based on runtime arguments
   def client(token) do
-    Tesla.build_client [
+    Tesla.client([
       {Tesla.Middleware.Headers, [{"authorization", "token: " <> token }]}
-    ]
+    ])
   end
 end
 ```
@@ -157,27 +157,6 @@ GitHub.issues()
 client |> GitHub.issues()
 ```
 
-The `Tesla.build_client` function can take two arguments: `pre` and `post` middleware.
-The first list (`pre`) will be included before any other middleware. In case there is a need
-to inject middleware at the end you can pass a second list (`post`). It will be put just
-before adapter. In fact, one can even dynamically override the adapter.
-
-For example, a private (per user) cache could be implemented as:
-
-```elixir
-def new(user) do
-  Tesla.build_client [], [
-    fn env, next ->
-      case my_private_cache.fetch(user, env) do
-        {:ok, env} -> {:ok, env}        # return cached response
-        :error -> Tesla.run(env, next)  # make real request
-      end
-    end
-  end
-end
-```
-
-
 ## Adapters
 
 Tesla supports multiple HTTP adapter that do the actual HTTP request processing.

lib/tesla.ex

@@ -64,13 +64,18 @@ defmodule Tesla.Env do
 end
 
 defmodule Tesla.Client do
+  @type adapter :: atom | {atom, Tesla.Env.opts()}
+  @type middleware :: atom | {atom, Tesla.Env.opts()}
+
   @type t :: %__MODULE__{
           pre: Tesla.Env.stack(),
-          post: Tesla.Env.stack()
+          post: Tesla.Env.stack(),
+          adapter: adapter | nil
         }
   defstruct fun: nil,
             pre: [],
-            post: []
+            post: [],
+            adapter: nil
 end
 
 defmodule Tesla.Middleware do
@@ -86,9 +91,9 @@ defmodule Tesla.Middleware do
 
       plug Tesla.Middleware.BaseUrl, "https://example.com"
 
-  or inside tuple in case of dynamic middleware (`Tesla.build_client/2`)
+  or inside tuple in case of dynamic middleware (`Tesla.client/1`)
 
-      Tesla.build_client([{Tesla.Middleware.BaseUrl, "https://example.com"}])
+      Tesla.client([{Tesla.Middleware.BaseUrl, "https://example.com"}])
 
   ## Writing custom middleware
 
@@ -298,13 +303,14 @@ defmodule Tesla do
 
   defp prepare(module, %{pre: pre, post: post} = client, options) do
     env = struct(Env, options ++ [__module__: module, __client__: client])
-    stack = pre ++ module.__middleware__ ++ post ++ [effective_adapter(module)]
+    stack = pre ++ module.__middleware__ ++ post ++ [effective_adapter(module, client)]
     {env, stack}
   end
 
   @doc false
-  def effective_adapter(module) do
-    with nil <- adapter_per_module_from_config(module),
+  def effective_adapter(module, client \\ %Tesla.Client{}) do
+    with nil <- client.adapter,
+         nil <- adapter_per_module_from_config(module),
          nil <- adapter_per_module(module),
          nil <- adapter_from_config() do
       adapter_default()
@@ -421,26 +427,63 @@ defmodule Tesla do
   def put_body(%Env{} = env, body), do: %{env | body: body}
 
   @doc """
-  Dynamically build client from list of middlewares.
+  Dynamically build client from list of middlewares and/or adapter.
 
   ```
-  defmodule ExampleAPI do
-    use Tesla
+  # add dynamic middleware
+  client = Tesla.client([{Tesla.Middleware.Headers, [{"authorization", token}]}])
+  Tesla.get(client, "/path")
+
+  # configure adapter in runtime
+  client = Tesla.client([], Tesla.Adapter.Hackney)
+  client = Tesla.client([], {Tesla.Adapter.Hackney, pool: :my_pool)
+  Tesla.get(client, "/path")
+
+  # complete module example
+  defmodule MyApi do
+    # note there is no need for `use Tesla`
+
+    @middleware [
+      {Tesla.Middleware.BaseUrl, "https://example.com"},
+      Tesla.Middleware.JSON,
+      Tesla.Middleware.Logger
+    ]
+
+    @adapter Tesla.Adapter.Hackney
+
+    def new(opts) do
+      # do any middleware manipulation you need
+      middleware = [
+        {Tesla.Middleware.BasicAuth, username: opts[:username], password: opts[:password]}
+      ] ++ @middleware
+
+      # allow configuring adapter in runtime
+      adapter = opts[:adapter] || @adapter
+
+      # use Tesla.client/2 to put it all together
+      Tesla.client(middleware, adapter)
+    end
 
-    def new(token) do
-      Tesla.build_client([
-        {Tesla.Middleware.Headers, [{"authorization", token}]
-      ])
+    def get_something(client, id) do
+      # pass client directly to Tesla.get/2
+      Tesla.get(client, "/something/\#{id}")
+      # ...
     end
   end
 
-  client = ExampleAPI.new(token: "abc")
-  client |> ExampleAPI.get("/me")
+  client = MyApi.new(username: "admin", password: "secret")
+  MyApi.get_something(client, 42)
   ```
   """
+  @since "1.2.0"
+  @spec client([Tesla.Client.middleware()], Tesla.Client.adapter()) :: Tesla.Client.t()
+  def client(middleware, adapter \\ nil), do: Tesla.Builder.client(middleware, [], adapter)
+
+  @deprecated "Use client/1 or client/2 instead"
   def build_client(pre, post \\ []), do: Tesla.Builder.client(pre, post)
 
-  def build_adapter(fun), do: Tesla.Builder.client([], [fn env, _next -> fun.(env) end])
+  @deprecated "Use client/1 or client/2 instead"
+  def build_adapter(fun), do: Tesla.Builder.client([], [], fun)
 
   def build_url(url, []), do: url
 

lib/tesla/builder.ex

@@ -169,7 +169,9 @@ defmodule Tesla.Builder do
     end
   end
 
-  def client(pre, post), do: %Tesla.Client{pre: runtime(pre), post: runtime(post)}
+  def client(pre, post, adapter \\ nil) do
+    %Tesla.Client{pre: runtime(pre), post: runtime(post), adapter: runtime(adapter)}
+  end
 
   @default_opts []
 
@@ -202,6 +204,7 @@ defmodule Tesla.Builder do
     Tesla.Migration.breaking_alias!(kind, name, caller)
   end
 
+  defp runtime(nil), do: nil
   defp runtime(list) when is_list(list), do: Enum.map(list, &runtime/1)
   defp runtime({module, opts}) when is_atom(module), do: {module, :call, [opts]}
   defp runtime(fun) when is_function(fun), do: {:fn, fun}

lib/tesla/middleware/basic_auth.ex

@@ -16,7 +16,7 @@ defmodule Tesla.Middleware.BasicAuth do
 
     # dynamic user & pass
     def new(username, password, opts \\\\ %{}) do
-      Tesla.build_client [
+      Tesla.client [
         {Tesla.Middleware.BasicAuth, Map.merge(%{username: username, password: password}, opts)}
       ]
     end

lib/tesla/middleware/digest_auth.ex

@@ -15,7 +15,7 @@ defmodule Tesla.Middleware.DigestAuth do
     use Tesla
 
     def client(username, password, opts \\ %{}) do
-      Tesla.build_client [
+      Tesla.client [
         {Tesla.Middleware.DigestAuth, Map.merge(%{username: username, password: password}, opts)}
       ]
     end

lib/tesla/migration.ex

@@ -91,7 +91,7 @@ defmodule Tesla.Migration do
       message: """
 
         Using anonymous function as client has been removed.
-        Use `Tesla.build_client` instead
+        Use `Tesla.client/2` instead
 
         See #{@breaking_client_fun}
       """

test/tesla/middleware/basic_auth_test.exs

@@ -11,7 +11,7 @@ defmodule Tesla.Middleware.BasicAuthTest do
     end
 
     def client(username, password, opts \\ %{}) do
-      Tesla.build_client([
+      Tesla.client([
         {
           Tesla.Middleware.BasicAuth,
           Map.merge(
@@ -26,7 +26,7 @@ defmodule Tesla.Middleware.BasicAuthTest do
     end
 
     def client() do
-      Tesla.build_client([Tesla.Middleware.BasicAuth])
+      Tesla.client([Tesla.Middleware.BasicAuth])
     end
   end
 

test/tesla/middleware/digest_auth_test.exs

@@ -27,7 +27,7 @@ defmodule Tesla.Middleware.DigestAuthTest do
     end
 
     def client(username, password, opts \\ %{}) do
-      Tesla.build_client([
+      Tesla.client([
         {
           Tesla.Middleware.DigestAuth,
           Map.merge(
@@ -48,7 +48,7 @@ defmodule Tesla.Middleware.DigestAuthTest do
     use Tesla
 
     def client do
-      Tesla.build_client([
+      Tesla.client([
         {Tesla.Middleware.DigestAuth, nil}
       ])
     end

test/tesla_test.exs

@@ -149,22 +149,14 @@ defmodule TeslaTest do
       end
     end
 
-    test "override adapter - Tesla.build_client" do
+    test "override adapter - Tesla.client" do
       client =
-        Tesla.build_client([], [
-          fn env, _next ->
+        Tesla.client(
+          [],
+          fn env ->
             {:ok, %{env | body: "new"}}
           end
-        ])
-
-      assert {:ok, %{body: "new"}} = DynamicClient.help(client)
-    end
-
-    test "override adapter - Tesla.build_adapter" do
-      client =
-        Tesla.build_adapter(fn env ->
-          {:ok, %{env | body: "new"}}
-        end)
+        )
 
       assert {:ok, %{body: "new"}} = DynamicClient.help(client)
     end