ReverseProxyPlug

https://hexdocs.pm/reverse_proxy_plug
Admin
ReverseProxyPlug is an Elixir reverse proxy plug for proxying HTTP requests to upstream URLs using...
Tokens:6,776
Snippets:74
Trust Score:9
Update:1 month ago
Show doc for...
Tokens:
Raw
### start_link(opts)

Source: https://hexdocs.pm/reverse_proxy_plug_websocket/ReverseProxyPlugWebsocket.ProxyProcess.html

Starts a new proxy process. This function initializes the GenServer that manages the bidirectional WebSocket proxy.

```APIDOC
## start_link(opts)

### Description
Starts a new proxy process. This function initializes the GenServer that manages the bidirectional WebSocket proxy.

### Function
`start_link(opts)`

### Parameters
#### Options
- **:adapter** (module) - Required - The WebSocket client adapter module.
- **:upstream_uri** (string) - Required - The upstream WebSocket URI.
- **:headers** (list) - Optional - Additional headers to send to upstream.
- **:client_pid** (pid) - Required - The client WebSocket process PID.

### Returns
- `{:ok, pid}` - On successful start.
- `{:error, reason}` - If the process fails to start.
```

--------------------------------

### child_spec(init_arg)

Source: https://hexdocs.pm/reverse_proxy_plug_websocket/ReverseProxyPlugWebsocket.ProxyProcess.html

Returns a specification to start this module under a supervisor. This is used for integrating the proxy process into a supervision tree.

```APIDOC
## child_spec(init_arg)

### Description
Returns a specification to start this module under a supervisor. This is used for integrating the proxy process into a supervision tree.

### Function
`child_spec(init_arg)`

### Parameters
- **init_arg** (term) - Required - The argument passed to `start_link/1` when starting the process.

### Returns
- A supervisor child specification (map).
```

--------------------------------

### ReverseProxyPlug.HTTPClient.MaybeRedirect

Source: https://hexdocs.pm/reverse_proxy_plug/api-reference.html

Provides automatic redirect following for GET and HEAD requests when the :follow_redirect option is enabled.

```APIDOC
## ReverseProxyPlug.HTTPClient.MaybeRedirect

### Description
If the option `:follow_redirect` is given to a request, HTTP redirects are automatically followed if the method is set to `:get` or `:head` and the response's `status_code` is `301`, `302` or `307`.

### Usage
Pass `follow_redirect: true` in the request options to enable automatic redirect following.

### Example
```elixir
ReverseProxyPlug.HTTPClient.request(method, url, body, headers, follow_redirect: true)
```
```

--------------------------------

### init(opts)

Source: https://hexdocs.pm/reverse_proxy_plug/ReverseProxyPlug.html

Callback implementation for Plug.init/1. Initializes the plug options.

```APIDOC
## init(opts)

### Description
Callback implementation for `Plug.init/1`. This function is called at compile time to initialize the plug options.

### Function Signature
```elixir
@spec init(Keyword.t()) :: Keyword.t()
```

### Parameters
- **opts** (Keyword.t()) - Required - Options to initialize.

### Returns
- **Keyword.t()** - The initialized options.
```

--------------------------------

### Configure HTTP client adapter per-plug

Source: https://hexdocs.pm/reverse_proxy_plug/readme.html

Sets the HTTP client adapter per-plug, overriding any global config. Must be set unless global config is set, otherwise defaults to HTTPoison or raises if not present.

```elixir
plug ReverseProxyPlug, client: ReverseProxyPlug.HTTPClient.Adapters.Tesla
```

--------------------------------

### Configure HTTP client adapter globally

Source: https://hexdocs.pm/reverse_proxy_plug/readme.html

Sets the HTTP client adapter globally in config. Must be set unless overridden per-plug, otherwise defaults to HTTPoison or raises if not present.

```elixir
config :reverse_proxy_plug, :http_client, ReverseProxyPlug.HTTPClient.Adapters.HTTPoison
```

--------------------------------

### call(conn, opts)

Source: https://hexdocs.pm/reverse_proxy_plug/ReverseProxyPlug.html

Callback implementation for Plug.call/2. Invoked by Plug to handle the request.

```APIDOC
## call(conn, opts)

### Description
Callback implementation for `Plug.call/2`. This function is called by Plug to process the incoming connection.

### Function Signature
```elixir
@spec call(Plug.Conn.t(), Keyword.t()) :: Plug.Conn.t()
```

### Parameters
- **conn** (Plug.Conn.t()) - Required - The connection struct.
- **opts** (Keyword.t()) - Required - Options for the plug.

### Returns
- **Plug.Conn.t()** - The updated connection struct.
```

--------------------------------

### Plug with status_callbacks option

Source: https://hexdocs.pm/reverse_proxy_plug/readme.html

Configures ReverseProxyPlug with a status callback for handling 404 responses in streaming mode.

```APIDOC
## [PLUG] ReverseProxyPlug

### Description
Configures ReverseProxyPlug with a status callback for handling 404 responses in streaming mode.

### Method
Plug

### Endpoint
N/A

### Parameters
#### Plug Options
- **upstream** (string) - Required - The upstream URL to proxy requests to.
- **status_callbacks** (map) - Optional - A map from status code to handler function. The handler is called when an HTTPoison.AsyncStatus message with the given status is received.
- **response_mode** (atom) - Optional - Must be `:stream` (default) when using status_callbacks.

### Request Example
```elixir
plug(ReverseProxyPlug,
  upstream: "example.com",
  status_callbacks: %{404 => &handle_404/2}
)
```

### Response
#### Success Response (200)
- **conn** (Plug.Conn) - The connection after the handler has consumed all remaining response parts and responded to the client.

#### Response Example
```elixir
# The handler must consume all remaining HTTPoison async response parts, respond to the client, and return the Plug.Conn.
```

### Error Handling
- If the status callback is not provided, the response is passed through as usual.
- `:status_callbacks` must only be given when `:response_mode` is `:stream` (the default).
```

--------------------------------

### Forward requests to upstream with Plug.Router.forward/2

Source: https://hexdocs.pm/reverse_proxy_plug/readme.html

Proxies all requests matching /foo to the specified upstream. A request to /foo/baz becomes http://example.com/bar/baz.

```elixir
forward("/foo", to: ReverseProxyPlug, upstream: "//example.com/bar")
```

--------------------------------

### response(arg, conn, opts)

Source: https://hexdocs.pm/reverse_proxy_plug/ReverseProxyPlug.html

Handles the response from the upstream server. This is a helper function for processing the response.

```APIDOC
## response(arg, conn, opts)

### Description
Handles the response from the upstream server. This is a helper function for processing the response.

### Parameters
- **arg** (any) - Required - The response argument.
- **conn** (Plug.Conn.t()) - Required - The connection struct.
- **opts** (Keyword.t()) - Required - Options for the response.

### Returns
- The processed response.
```

--------------------------------

### ReverseProxyPlug

Source: https://hexdocs.pm/reverse_proxy_plug/api-reference.html

The main module for reverse proxying. Users can call this module to set up reverse proxy functionality in their Plug applications.

```APIDOC
## ReverseProxyPlug

### Description
The main ReverseProxyPlug module. Provides the core reverse proxy functionality for Plug-based applications.

### Usage
This module is used as a Plug in your application's router or endpoint. It forwards incoming requests to a configured upstream server.

### Configuration
Configure the upstream URL and other options via the `:reverse_proxy_plug` application environment or directly in the plug call.

### Example
```elixir
plug ReverseProxyPlug, upstream: "http://example.com"
```

### Related Modules
- `ReverseProxyPlug.HTTPClient` - Behaviour for HTTP clients.
- `ReverseProxyPlug.HTTPClient.Adapters.Finch` - Finch adapter.
- `ReverseProxyPlug.HTTPClient.Adapters.HTTPoison` - HTTPoison adapter.
- `ReverseProxyPlug.HTTPClient.Adapters.Req` - Req adapter.
- `ReverseProxyPlug.HTTPClient.Adapters.Tesla` - Tesla adapter.
- `ReverseProxyPlug.HTTPClient.Error` - Error handling.
- `ReverseProxyPlug.HTTPClient.MaybeRedirect` - Redirect following.
- `ReverseProxyPlug.HTTPClient.Request` - Request struct.
- `ReverseProxyPlug.HTTPClient.Response` - Response struct.
```

--------------------------------

### request(conn, body, opts)

Source: https://hexdocs.pm/reverse_proxy_plug/ReverseProxyPlug.html

Makes a request to the upstream server. This is a helper function for performing the reverse proxy request.

```APIDOC
## request(conn, body, opts)

### Description
Makes a request to the upstream server. This is a helper function for performing the reverse proxy request.

### Parameters
- **conn** (Plug.Conn.t()) - Required - The connection struct.
- **body** (any) - Required - The request body.
- **opts** (Keyword.t()) - Required - Options for the request.

### Returns
- The response.
```

--------------------------------

### request(t)

Source: https://hexdocs.pm/reverse_proxy_plug/ReverseProxyPlug.HTTPClient.html

Callback that performs an HTTP request and returns a response or a redirect. Implementations must return either an ok tuple with a response or maybe_redirect, or an error tuple.

```APIDOC
## request(t)

### Description
Performs an HTTP request and returns the response or a redirect.

### Callback Signature
```elixir
@callback request(ReverseProxyPlug.HTTPClient.Request.t()) ::
  {:ok,
   ReverseProxyPlug.HTTPClient.Response.t()
   | ReverseProxyPlug.HTTPClient.MaybeRedirect.t()}
  | {:error, error()}
```

### Parameters
- **request** (ReverseProxyPlug.HTTPClient.Request.t()) - The request to send.

### Return Values
- **{:ok, ReverseProxyPlug.HTTPClient.Response.t() | ReverseProxyPlug.HTTPClient.MaybeRedirect.t()}** - Success with a response or a maybe_redirect.
- **{:error, error()}** - Failure with an error.
```

--------------------------------

### Phoenix Router forward with ReverseProxyPlug

Source: https://hexdocs.pm/reverse_proxy_plug/readme.html

Forwards a route to ReverseProxyPlug in a Phoenix router with an upstream and error callback.

```APIDOC
## [PLUG] Phoenix Router forward

### Description
Forwards a route to ReverseProxyPlug in a Phoenix router, specifying an upstream and an error callback.

### Method
Plug

### Endpoint
`/api/foo`

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Request Example
```elixir
scope "/api" do
  pipe_through :api

  forward "/foo", ReverseProxyPlug,
    upstream: &Settings.foo_url/0,
    error_callback: &__MODULE__.log_reverse_proxy_error/1

  def log_reverse_proxy_error(error) do
    Logger.warn("ReverseProxyPlug network error: #{inspect(error)}")
  end
end
```

### Response
#### Success Response (200)
- **conn** (Plug.Conn) - The connection after the reverse proxy has completed.

#### Response Example
```elixir
# The response from the upstream is passed through to the client.
```

### Error Handling
- If a network error occurs, the `error_callback` is invoked with the error.
```

--------------------------------

### Forward requests with scheme and port in upstream

Source: https://hexdocs.pm/reverse_proxy_plug/readme.html

Specifies the scheme and port in the upstream URL. The upstream must be parseable by URI.parse/1 or a function returning one.

```elixir
forward("/foo", to: ReverseProxyPlug, upstream: "https://example.com:4200/bar")
```

--------------------------------

### Add reverse_proxy_plug dependency in mix.exs

Source: https://hexdocs.pm/reverse_proxy_plug/readme.html

Adds the reverse_proxy_plug dependency to your Elixir project. Required for using the library.

```elixir
def deps do
  [
    {:reverse_proxy_plug, "~> 3.0"}
  ]
end
```

--------------------------------

### ReverseProxyPlug.HTTPClient.Adapters.Req

Source: https://hexdocs.pm/reverse_proxy_plug/api-reference.html

Req adapter for the ReverseProxyPlug.HTTPClient behaviour. Users can use this adapter to perform reverse proxy requests with Req.

```APIDOC
## ReverseProxyPlug.HTTPClient.Adapters.Req

### Description
Req adapter for the `ReverseProxyPlug.HTTPClient` behaviour. Implements the HTTP client interface using Req.

### Usage
Configure as the HTTP client in your reverse proxy setup.

### Example
```elixir
plug ReverseProxyPlug, http_client: ReverseProxyPlug.HTTPClient.Adapters.Req
```
```

--------------------------------

### ReverseProxyPlug.HTTPClient.Adapters.HTTPoison

Source: https://hexdocs.pm/reverse_proxy_plug/api-reference.html

HTTPoison adapter for the ReverseProxyPlug.HTTPClient behaviour. Users can use this adapter to perform reverse proxy requests with HTTPoison.

```APIDOC
## ReverseProxyPlug.HTTPClient.Adapters.HTTPoison

### Description
HTTPoison adapter for the `ReverseProxyPlug.HTTPClient` behaviour. Implements the HTTP client interface using HTTPoison.

### Usage
Configure as the HTTP client in your reverse proxy setup.

### Example
```elixir
plug ReverseProxyPlug, http_client: ReverseProxyPlug.HTTPClient.Adapters.HTTPoison
```
```

--------------------------------

### ReverseProxyPlug.HTTPClient.Adapters.Finch

Source: https://hexdocs.pm/reverse_proxy_plug/api-reference.html

Finch adapter for the ReverseProxyPlug.HTTPClient behaviour. Users can use this adapter to perform reverse proxy requests with Finch.

```APIDOC
## ReverseProxyPlug.HTTPClient.Adapters.Finch

### Description
Finch adapter for the `ReverseProxyPlug.HTTPClient` behaviour. Implements the HTTP client interface using Finch.

### Usage
Configure as the HTTP client in your reverse proxy setup.

### Example
```elixir
plug ReverseProxyPlug, http_client: ReverseProxyPlug.HTTPClient.Adapters.Finch
```
```

--------------------------------

### Plug with custom body reader

Source: https://hexdocs.pm/reverse_proxy_plug/readme.html

Configures Plug.Parsers with a custom body reader to extract raw request bodies for later use.

```APIDOC
## [PLUG] Plug.Parsers with custom body_reader

### Description
Configures Plug.Parsers with a custom body reader to extract raw request bodies and store them in the connection for later use.

### Method
Plug

### Endpoint
N/A

### Parameters
#### Plug Options
- **body_reader** (tuple) - Required - A tuple `{Module, :function, []}` specifying the custom body reader function.
- **Other Plug.Parsers options** - Optional - Additional options as per Plug.Parsers.

### Request Example
```elixir
plug Plug.Parsers,
  body_reader: {CacheBodyReader, :read_body, []},
  # ...
```

### Response
#### Success Response (200)
- **conn** (Plug.Conn) - The connection with the raw body stored in `conn.assigns[:raw_body]`.

#### Response Example
```elixir
# The custom body reader stores the raw body in conn.assigns[:raw_body] and returns {:ok, body, conn}.
```

### Error Handling
- The custom body reader ignores the updated connection returned by `Plug.Conn.read_body/2` to not break CSRF.
```

--------------------------------

### ReverseProxyPlug.HTTPClient

Source: https://hexdocs.pm/reverse_proxy_plug/api-reference.html

Behaviour defining the HTTP client interface needed for reverse proxying. Users can implement this behaviour to provide custom HTTP clients.

```APIDOC
## ReverseProxyPlug.HTTPClient

### Description
Behaviour defining the HTTP client interface needed for reverse proxying. Implement this behaviour to integrate a custom HTTP client.

### Callbacks
- `request/1` - Sends an HTTP request.
- `request/2` - Sends an HTTP request with options.
- `request/3` - Sends an HTTP request with method, url, and body.
- `request/4` - Sends an HTTP request with method, url, body, and headers.
- `request/5` - Sends an HTTP request with method, url, body, headers, and options.

### Example
```elixir
defmodule MyClient do
  @behaviour ReverseProxyPlug.HTTPClient
  # implement callbacks
end
```
```

--------------------------------

### ReverseProxyPlug.HTTPClient.Request

Source: https://hexdocs.pm/reverse_proxy_plug/api-reference.html

Represents the properties of an HTTP request in the reverse proxy client.

```APIDOC
## ReverseProxyPlug.HTTPClient.Request

### Description
`Request` properties. Represents an HTTP request to be sent by the reverse proxy.

### Fields
- `method` (atom) - The HTTP method (e.g., :get, :post).
- `url` (binary) - The request URL.
- `headers` (list) - Request headers.
- `body` (binary) - Request body.
- `options` (list) - Additional request options.

### Usage
Constructed by the reverse proxy and passed to the HTTP client adapter.
```

--------------------------------

### read_body(conn, opts \\ [])

Source: https://hexdocs.pm/reverse_proxy_plug/ReverseProxyPlug.html

Reads the request body from the connection. This is a helper function for reading the body.

```APIDOC
## read_body(conn, opts \\ [])

### Description
Reads the request body from the connection. This is a helper function for reading the body.

### Parameters
- **conn** (Plug.Conn.t()) - Required - The connection struct.
- **opts** (list) - Optional - Options for reading the body. Defaults to `[]`.

### Returns
- The read body.
```

--------------------------------

### ReverseProxyPlug.HTTPClient.Adapters.Tesla

Source: https://hexdocs.pm/reverse_proxy_plug/api-reference.html

Tesla adapter for the ReverseProxyPlug.HTTPClient behaviour. Users can use this adapter to perform reverse proxy requests with Tesla.

```APIDOC
## ReverseProxyPlug.HTTPClient.Adapters.Tesla

### Description
Tesla adapter for the `ReverseProxyPlug.HTTPClient` behaviour. Implements the HTTP client interface using Tesla.

### Usage
Configure as the HTTP client in your reverse proxy setup.

### Example
```elixir
plug ReverseProxyPlug, http_client: ReverseProxyPlug.HTTPClient.Adapters.Tesla
```
```

--------------------------------

### ReverseProxyPlug.HTTPClient.Response

Source: https://hexdocs.pm/reverse_proxy_plug/api-reference.html

HTTP Client response model. Represents the response from the upstream server.

```APIDOC
## ReverseProxyPlug.HTTPClient.Response

### Description
HTTP Client response model. Represents the response returned by the upstream server.

### Fields
- `status` (integer) - The HTTP status code.
- `headers` (list) - Response headers.
- `body` (binary) - Response body.

### Usage
Returned by HTTP client adapters after a successful request.
```

--------------------------------

### message(error)

Source: https://hexdocs.pm/reverse_proxy_plug/ReverseProxyPlug.HTTPClient.Error.html

Callback implementation for Exception.message/1. Returns the error message for the exception.

```APIDOC
## message(error)

### Description
Callback implementation for `Exception.message/1`. Returns the error message for the exception.

### Parameters
- **error** (t()) - The exception struct.

### Returns
- **String** - The error message.

```

--------------------------------

### client_frame(pid, frame)

Source: https://hexdocs.pm/reverse_proxy_plug_websocket/ReverseProxyPlugWebsocket.ProxyProcess.html

Sends a frame from the client to be forwarded to upstream. This function is used to relay client WebSocket frames through the proxy.

```APIDOC
## client_frame(pid, frame)

### Description
Sends a frame from the client to be forwarded to upstream. This function is used to relay client WebSocket frames through the proxy.

### Function
`client_frame(pid, frame)`

### Parameters
- **pid** (pid) - Required - The process identifier of the proxy process.
- **frame** (term) - Required - The WebSocket frame to forward.

### Returns
- `:ok` - If the frame was successfully sent.
- `{:error, reason}` - If the frame could not be sent.
```

--------------------------------

### request_stream(t)

Source: https://hexdocs.pm/reverse_proxy_plug/ReverseProxyPlug.HTTPClient.html

Optional callback that performs a streaming HTTP request and returns an enumerable response. Implementations must return either an ok tuple with an enumerable or an error tuple.

```APIDOC
## request_stream(t)

### Description
Performs a streaming HTTP request and returns an enumerable response.

### Callback Signature
```elixir
@callback request_stream(ReverseProxyPlug.HTTPClient.Request.t()) ::
  {:ok, Enumerable.t()} | {:error, error()}
```

### Parameters
- **request** (ReverseProxyPlug.HTTPClient.Request.t()) - The request to send.

### Return Values
- **{:ok, Enumerable.t()}** - Success with an enumerable response.
- **{:error, error()}** - Failure with an error.
```

--------------------------------

### downcase_headers(headers)

Source: https://hexdocs.pm/reverse_proxy_plug/ReverseProxyPlug.html

Downcases the given headers. This is a helper function for normalizing header names.

```APIDOC
## downcase_headers(headers)

### Description
Downcases the given headers. This is a helper function for normalizing header names.

### Parameters
- **headers** (list) - Required - List of headers to downcase.

### Returns
- The downcased headers.
```

--------------------------------

### ReverseProxyPlug.HTTPClient.Error

Source: https://hexdocs.pm/reverse_proxy_plug/api-reference.html

Error module for the HTTP client. Represents errors that may occur during reverse proxy requests.

```APIDOC
## ReverseProxyPlug.HTTPClient.Error

### Description
Represents an error that occurred during an HTTP client operation in reverse proxying.

### Fields
- `reason` (term) - The reason for the error.
- `status` (integer) - The HTTP status code if applicable.
- `headers` (list) - Response headers if applicable.
- `body` (binary) - Response body if applicable.

### Usage
Returned by HTTP client adapters when a request fails.
```
Tokens:
Raw