# BridgeEx

[![Build Status](](
[![Module Version](](
[![Hex Docs](](
[![Total Downloads](](
[![Last Updated](](

A library to build bridges to GraphQL services.

## Usage

Bridges to Graphql services are defined by `use`ing the `BridgeEx.Graphql` macro as follows:

defmodule MyApp.SomeServiceBridge do
  use BridgeEx.Graphql, endpoint: "", decode_keys: :strings

  def my_query(%{} = variables) do
    call("a graphql query or mutation", variables, retry_policy: [max_retries: 1])

Besides `endpoint` and `decode_keys`, the following parameters can be optionally set when `use`ing `BridgeEx.Graphql`:

- `auth0`
- `encode_variables`
- `format_response`
- `format_variables`
- `http_headers`
- `http_options`
- `log_options`
- `max_attempts` `⚠ Deprecated in favour of retry_options in call method`

The option `decode_keys` determines how JSON keys in GraphQL responses are decoded. If you don't provide it, it is set by default to `:atoms`, which is **highly discouraged** since it may raise security concerns (see ["Decoding keys to atoms" in Jason documentation]( for more information). Other decoding modes are `:strings` and `:existing_atoms` which are safer. In a future version, this option will be set by default to `:strings`.

Refer to [the documentation]( for more details.

If you need more control on your requests you can use [``]( directly.

The library supports preloading queries from external files via the `BridgeEx.Extensions.ExternalResources` optional macro:

defmodule MyApp.SomeServiceBridge do
  use BridgeEx.Graphql, endpoint: "", decode_keys: :strings
  use BridgeEx.Extensions.ExternalResources, resources: [my_query: "my_query.graphql"]

  def my_query(%{} = variables), do: call(my_query(), variables)

### Runtime options

The options passed to the `BridgeEx.Graphql` macro are evaluated at compile time. If you need the value of one or more options to be evaluated at runtime (e.g. because they depend on environment variables), you can configure those options for a specific bridge in the application environment.

Each bridge will first try to get its options from the ones passed to `use`. If those are not defined, it will try to get them from the `:bridge_ex, __MODULE__` key in the application environment. If the latter are not present either, it will resort to the default values.

Here's an example:

# config.exs
config :bridge_ex, SomeBridge, endpoint: "http://some-service/graphql"

# some_bridge.ex
defmodule SomeBridge do
  use BridgeEx.Graphql

  def my_query(%{} = variables) do
    # this will call http://some-service/graphql
    call("a graphql query or mutation", variables)

NOTE: If you pass the same option both in the application configuration and via `use`, the one passed via `use` (evaluated at compile time) will have the precedence.

### Call options

When `call`ing you can provide the following options, some of which override the ones provided at the bridge level:

- `headers` (overrides `http_headers` bridge option)
- `options` (overrides `http_options` bridge option)
- `retry_options`

### Return values

`call` can return one of the following values:

- `{:ok, graphql_response}` on success
- `{:error, graphql_error}` on graphql error (i.e. 200 status code but `errors` array is not `nil`)
- `{:error, {:bad_response, status_code}}` on non 200 status code
- `{:error, {:http_error, reason}}` on http error e.g. `:econnrefused`

### Customizing the retry options

By default if `max_attempts` is greater than `1`, the bridge retries every error regardless of its value (⚠ This way is deprecated). This behaviour can be customized by providing the `retry_options` to a `call`.
`retry_options`: override configuration regarding retries, namely

- `delay`: meaning depends on `timing`
- `:constant`: retry ever `delay` ms
- `:exponential`: start retrying with `delay` ms
- `max_retries`. Defaults to `0`
- `policy`: a function that takes an error as input and returns `true`/`false` to indicate whether to retry the error or not. Defaults to "always retry" (`fn _ -> true end`).
- `timing`: either `:exponential`or`:constant`, indicates how frequently retries are made (e.g. every 1s, in an exponential manner and so on). Defaults to `:exponential`

A policy example:

retry_policy = fn errors ->
  case errors do
    {:bad_response, 400} -> true
    {:http_error, _reason} -> true
    [%{message: "some_error", extensions: %{code: "SOME_CODE"}}] -> true
    _ -> false

defmodule BridgeWithCustomRetry do
  use BridgeEx.Graphql,
    endpoint: "", decode_keys: :strings
end"myquery", %{}, retry_options: [policy: retry_policy, max_retries: 2])

### (Deprecated) Global configuration

The following configuration parameters can be set globally for all bridges in the app, by setting them inside your `config.exs`:

- `config :bridge_ex, log_options: [log_query_on_error: true, log_response_on_error: false]` to customize logging in your bridges

Please note that this config has been **deprecated** since it's a footgun for umbrella apps and bad library design in general.

### Authenticating calls via Auth0

`bridge_ex` supports authentication of machine-to-machine calls via Auth0, through the [prima_auth0_ex]( library.

To use this feature do the following:

- update your `config.exs` with the necessary config to create API consumers with `prima_auth0_ex`, see [the documentation](
- add `:prima_auth0_ex` as a dependency in your mix project

Then configure your bridge with the audience of the target service:

use BridgeEx.Graphql,
  endpoint: "...",
  decode_keys: :strings,
  auth0: [
    enabled: true,
    audience: "target_audience",
    # You can optionally specify a client (in case you defined multiple ones)
    # Otherwise, the :default_client will be used instead
    # client: :target_client

Note that Auth0 integration **must be explicitly enabled for each bridge** where you want it by setting `auth0: [enable: true]`, as per the example above.

## Testing your bridge

As a good practice, if you want to mock your bridge for testing, you _should_ define a behaviour:

defmodule MyApp.SomeService do
  @callback my_cool_query(any()) :: {:ok, map()} | {:error, any()}

Then implement it for your bridge:

defmodule MyApp.SomeServiceBridge do
  @behaviour MyApp.SomeService

  use BridgeEx.Graphql, endpoint: "..."

And finally implement it again for the mock:

defmodule MyApp.SomeServiceBridgeMock do
  @behaviour MyApp.SomeService

  alias BridgeEx.Graphql.Utils

  def my_cool_query(%{} = variables) do!("some_mock_file.json")
    |> Json.decode!(keys: :atoms)
    # required to parse data
    |> Utils.parse_response()
    # optional, if you want to format the response
    # |> BridgeEx.Graphql.Formatter.SnakeCase.format()

You can now set the right module in your `config/*` directory:

config :my_app, :some_service_bridge, MyApp.SomeServiceBridge

# or

config :my_app, :some_service_bridge, MyApp.SomeServiceBridgeMock

And use it in your app from configuration:

@some_service Application.compile_env!(:my_app, :some_service_bridge)

# ...

@some_service.my_cool_query(%{var: 2})

See [example](example) directory for an implementation, it also works in `dev` and `test` environments.

## Development

`mix deps.get && mix test`

## Installation

The package can be installed by adding `bridge_ex` to your list of dependencies in `mix.exs`:

def deps do
    {:bridge_ex, "~> 2.0.0"}
    # only if you want auth0 too
    # {:prima_auth0_ex, "~> 0.3.0"}

## Copyright and License

Copyright (c) 2020

This work is free. You can redistribute it and/or modify it under the
terms of the MIT License. See the [](./ file for more details.