Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
# 0.9.0

* Added the `unix_socket` request option to both clients and connection managers.

# 0.8.0

## Breaking Changes
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ An HTTP Client library built around [Mint](https://github.com/elixir-mint/mint),
```elixir
{:ok, resp} = Pepper.HTTP.Client.request(method, url, headers, body, options)

{:ok, resp} = Pepper.HTTP.Client.request(:get, "https://example.com", [{"user-agent", "pepper-http/0.6.0"}], nil, [])
{:ok, resp} = Pepper.HTTP.Client.request(:get, "https://example.com", [{"user-agent", "pepper-http/0.9.0"}], nil, [])

resp.status_code # => 200
resp.headers # => [{"content-type", "text/plain"}, {"content-length", "12"}]
Expand Down
27 changes: 27 additions & 0 deletions docs/clients.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,33 @@ case result do
end
```

### Unix Domain Sockets

Both clients accept `unix_socket: "/path/to/service.sock"` with either connection manager:

```elixir
Pepper.HTTP.ContentClient.get(
"http://localhost/api/status",
[],
[],
unix_socket: "/tmp/service.sock"
)
```

Pepper connects to the socket file instead of resolving the URL's host or opening a TCP
connection. The URL still supplies the HTTP scheme, host, port, request path, and query.
For example, the request above sends `GET /api/status` with `Host: localhost`.
HTTP/1 requests preserve an explicitly supplied `Host` header.

`http://` sends plain HTTP over the socket; `https://` uses TLS over the socket, with the
URL's hostname used for certificate verification and SNI unless `connect_options[:hostname]`
overrides it. Existing `connect_options` and timeouts apply. Proxy options cannot be
combined with `unix_socket`.

The socket path must be a non-empty string. Omit `unix_socket`, or set it to `nil`, to use
the usual TCP connection. Unix sockets require support from the operating system.
Pooled connections are kept separate by socket path, URL destination, and connection options.

### ContentClient Usage

If you are in need of something more featured, Pepper provides a ContentClient which can handle most common request body types and response bodies.
Expand Down
16 changes: 15 additions & 1 deletion lib/pepper/http/client.ex
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,10 @@ defmodule Pepper.HTTP.Client do
This is a simple base client and doesn't handle any special content-types on request or response.

Use the Pepper.HTTP.ContentClient instead if you need content-type handling.

Pass `unix_socket: "/path/to/service.sock"` to connect through a Unix domain socket.
The URL still specifies the HTTP host, port, path, and query. Both one-off and
pooled connections support this option.
"""
require Logger

Expand Down Expand Up @@ -40,6 +44,7 @@ defmodule Pepper.HTTP.Client do
| {:response_body_handler_options, any()}
| {:attempts, non_neg_integer()}
| {:connect_options, [connect_option()]}
| {:unix_socket, String.t() | nil}

@type uri_or_url :: URI.t() | String.t()

Expand Down Expand Up @@ -200,9 +205,18 @@ defmodule Pepper.HTTP.Client do
:recv_size,
:recv_timeout,
:connect_timeout,
:connect_options
:connect_options,
:unix_socket
]

defp validate_options!([{:unix_socket, path} = pair | rest], acc) do
unless is_nil(path) or (is_binary(path) and path != "" and not String.contains?(path, <<0>>)) do
raise ArgumentError, ":unix_socket must be a non-empty path string or nil"
end

validate_options!(rest, [pair | acc])
end

defp validate_options!(
[{key, _} = pair | rest], acc
) when key in @allowed_keys do
Expand Down
13 changes: 1 addition & 12 deletions lib/pepper/http/connection_manager/one_off.ex
Original file line number Diff line number Diff line change
Expand Up @@ -18,18 +18,7 @@ defmodule Pepper.HTTP.ConnectionManager.OneOff do

@spec request(term(), Request.t()) :: {:ok, Response.t()} | {:error, error_reasons()}
def request(_id, %Request{} = request) do
connect_options =
Keyword.merge(
[
mode: :passive,
transport_opts: [
timeout: request.options[:connect_timeout],
],
],
Keyword.get(request.options, :connect_options, [])
)

case Mint.HTTP.connect(request.scheme, request.uri.host, request.uri.port, connect_options) do
case connect(request, :passive) do
{:ok, conn} ->
{request, is_stream?, body} =
determine_if_body_should_stream(conn, request)
Expand Down
7 changes: 3 additions & 4 deletions lib/pepper/http/connection_manager/pooled.ex
Original file line number Diff line number Diff line change
Expand Up @@ -51,8 +51,9 @@ defmodule Pepper.HTTP.ConnectionManager.Pooled do
alias Pepper.HTTP.ConnectError

import Pepper.HTTP.Utils, only: [safe_reduce_ets_table: 3]
import Pepper.HTTP.ConnectionManager.Utils, only: [connection_key: 1]

@type conn_key :: {scheme::atom(), host::String.t(), port::integer(), Keyword.t()}
@type conn_key :: Pepper.HTTP.ConnectionManager.Utils.conn_key()

@type connection_id :: GenServer.server()

Expand Down Expand Up @@ -213,9 +214,7 @@ defmodule Pepper.HTTP.ConnectionManager.Pooled do
def handle_call({:request, %Pepper.HTTP.Request{} = request}, from, %State{} = state) do
start_time = System.monotonic_time(:microsecond)
request = %{request | time: start_time}
connect_options = Keyword.get(request.options, :connect_options, [])

key = {request.scheme, request.uri.host, request.uri.port, connect_options}
key = connection_key(request)
case checkout_connection(key, state) do
{:empty, state} ->
ex = %CheckoutError{
Expand Down
27 changes: 5 additions & 22 deletions lib/pepper/http/connection_manager/pooled_connection.ex
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,7 @@ defmodule Pepper.HTTP.ConnectionManager.PooledConnection do
lifespan: nil,
pool_pid: nil,
conn: nil,
scheme: nil,
host: nil,
port: nil,
connection_key: nil,
status: :ok,
just_reconnected: false,
#
Expand Down Expand Up @@ -284,10 +282,8 @@ defmodule Pepper.HTTP.ConnectionManager.PooledConnection do
state

Mint.HTTP.open?(state.conn) ->
# ensure that connection's scheme, host and port matches the request
if request.scheme == state.scheme and
request.uri.host == state.host and
request.uri.port == state.port do
# Reclaimed workers must reconnect when the destination or options change.
if connection_key(request) == state.connection_key do
# it matches, so return the state as is
state
else
Expand All @@ -302,25 +298,12 @@ defmodule Pepper.HTTP.ConnectionManager.PooledConnection do
if state.conn do
{:ok, state}
else
req_options = request.options
connect_options = Keyword.merge(
[
mode: :active,
transport_opts: [
timeout: req_options[:connect_timeout],
],
],
Keyword.get(request.options, :connect_options, [])
)

case Mint.HTTP.connect(request.scheme, request.uri.host, request.uri.port, connect_options) do
case connect(request, :active) do
{:ok, conn} ->
{:ok, %{
state
| conn: conn,
scheme: request.scheme,
host: request.uri.host,
port: request.uri.port,
connection_key: connection_key(request),
just_reconnected: true
}
}
Expand Down
54 changes: 54 additions & 0 deletions lib/pepper/http/connection_manager/utils.ex
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,60 @@ defmodule Pepper.HTTP.ConnectionManager.Utils do

@type conn :: Mint.Core.Conn.conn()

@type conn_key :: {atom(), String.t(), integer(), String.t() | nil, Keyword.t()}

@spec connection_key(Request.t()) :: conn_key()
def connection_key(%Request{} = request) do
{request.scheme, request.uri.host, request.uri.port, Keyword.get(request.options, :unix_socket),
Keyword.get(request.options, :connect_options, [])}
end

@spec connect(Request.t(), mode()) :: {:ok, conn()} | {:error, term()}
def connect(%Request{} = request, mode) do
options =
Keyword.merge(
[mode: mode, transport_opts: [timeout: request.options[:connect_timeout]]],
Keyword.get(request.options, :connect_options, [])
)

case Keyword.get(request.options, :unix_socket) do
nil ->
Mint.HTTP.connect(request.scheme, request.uri.host, request.uri.port, options)

path ->
if Keyword.has_key?(options, :proxy) do
raise ArgumentError, ":unix_socket cannot be combined with a proxy"
end

options = Keyword.put_new(options, :hostname, request.uri.host)

case Mint.HTTP.connect(request.scheme, {:local, path}, 0, options) do
{:ok, conn} ->
{:ok, restore_http_port(conn, request.uri.port)}

{:error, _reason} = error ->
error
end
end
end

# Unix sockets require transport port 0. Mint also uses that port for HTTP
# identity, so restore the logical URL port before sending any requests.
defp restore_http_port(%Mint.HTTP1{} = conn, port) do
%{conn | port: port}
end

defp restore_http_port(%Mint.HTTP2{} = conn, port) do
authority =
if URI.default_port(conn.scheme) == port do
conn.hostname
else
"#{conn.hostname}:#{port}"
end

%{conn | port: port, authority: authority}
end

@spec timespan(function(), System.time_unit()) ::
{{start_at::integer(), end_at::integer()}, result::any()}
def timespan(callback, unit \\ :microsecond) when is_function(callback, 0) do
Expand Down
2 changes: 1 addition & 1 deletion mix.exs
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ defmodule Pepper.HTTP.MixProject do
def project do
[
app: :pepper_http,
version: "0.7.0",
version: "0.9.0",
elixir: "~> 1.12",
start_permanent: Mix.env() == :prod,
elixirc_options: [
Expand Down
73 changes: 73 additions & 0 deletions test/pepper/http/unix_socket_options_test.exs
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
defmodule Pepper.HTTP.UnixSocketOptionsTest do
use ExUnit.Case, async: true

import ExUnit.CaptureLog

alias Pepper.HTTP.Client
alias Pepper.HTTP.ContentClient

defmodule CaptureRequest do
def request(pid, request) do
send(pid, {:request, request})
{:error, :captured}
end
end

defp options(extra) do
[connection_manager: CaptureRequest, connection_manager_id: self()] ++ extra
end

test "ContentClient forwards the socket option and keeps the HTTP destination" do
log =
capture_log(fn ->
assert {:error, :captured} =
ContentClient.get(
"http://service.invalid:8080/api/status",
[detail: "full"],
[],
options(unix_socket: "/tmp/service.sock")
)
end)

refute log =~ "unexpected option"

assert_received {:request, request}
assert request.uri.host == "service.invalid"
assert request.uri.port == 8080
assert request.path == "/api/status?detail=full"
assert request.options[:unix_socket] == "/tmp/service.sock"
end

test "nil disables the socket option" do
assert {:error, :captured} =
Client.request(
:get,
"http://localhost/status",
[],
nil,
options(unix_socket: nil)
)

assert_received {:request, request}
assert request.options[:unix_socket] == nil
end

test "rejects invalid socket paths before submitting a request" do
for path <- ["", 123, String.to_charlist("/tmp/service.sock"), "/tmp/service\0.sock"] do
assert_raise ArgumentError, ":unix_socket must be a non-empty path string or nil", fn ->
Client.request(:get, "http://localhost/status", [], nil, options(unix_socket: path))
end
end

refute_received {:request, _}
end

test "rejects proxy options with a Unix socket before connecting" do
assert_raise ArgumentError, ":unix_socket cannot be combined with a proxy", fn ->
Client.request(:get, "http://localhost/status", [], nil,
unix_socket: "/tmp/service.sock",
connect_options: [proxy: {:http, "localhost", 8080, []}]
)
end
end
end
Loading
Loading