A repo is one cluster an application talks to: where it is, how to authenticate, which connection pool to use and how to cast what it returns.

A backend package builds on this module (use Dowser.OpenSearch.Repo, use Dowser.Elasticsearch.Repo); an application defines one module per kind of cluster:

defmodule MyApp.Search do
  use Dowser.OpenSearch.Repo, otp_app: :my_app
end

configures it under its own application, like an Ecto.Repo:

# config/runtime.exs
config :my_app, MyApp.Search,
  endpoint: System.fetch_env!("OPENSEARCH_URL"),
  auth: {:basic, "app", System.fetch_env!("OPENSEARCH_PASSWORD")},
  profile_opts: [max_sessions: 50]

and starts it in its supervision tree:

children = [MyApp.Repo, MyApp.Search, MyAppWeb.Endpoint]

Every request then names it — repo: MyApp.Search — or falls back to the backend's default repo (config :dowser_opensearch, default_repo: MyApp.Search).

Configuration

The fields of Dowser.Repo.Config, read from config :otp_app, Repo, merged with the options the repo is started with, then passed through init/2:

• :endpoint (required), :auth, :http_opts, :keys, :decoder, :encoder — see Dowser.Repo.Config.
• :profile — the :httpc profile; defaults to the name the repo was started under, so each repo — each instance of one — has its own connection pool. :profile_opts configures it.
• :verify — check at startup that the endpoint is the engine the backend package expects, and fail to start otherwise (default false). A cluster that is down then stops the application from booting, which is why it is off by default.

Static and dynamic repos

A repo started as itself — children = [MyApp.Search] — is a static repo, configured from the application environment.

The same module can also be started any number of times under other names, each with its own configuration — a cluster per tenant, say, or clusters only known at runtime. These are its dynamic instances:

{:ok, _pid} = MyApp.Search.start_link(name: :tenant_a, endpoint: "https://a.internal:9200")
{:ok, _pid} = MyApp.Search.start_link(name: :tenant_b, endpoint: "https://b.internal:9200")

A dynamic instance starts from the static configuration and overrides it with its own options, init/2 included (config[:name] is the instance's name). Start them under a DynamicSupervisor to add and remove them as tenants come and go.

Which instance a request reaches is decided per process, as with Ecto.Repo:

MyApp.Search.put_dynamic_repo(:tenant_a)
Dowser.OpenSearch.Search.search(query, repo: MyApp.Search)   # → tenant_a

MyApp.Search.with_dynamic_repo(:tenant_b, fn ->
  Dowser.OpenSearch.Search.search(query, repo: MyApp.Search) # → tenant_b
end)

or per call, without touching the process's choice, with {repo, name}:

Dowser.OpenSearch.Search.search(query, repo: {MyApp.Search, :tenant_a})

Started or not

Started, a repo resolves its configuration once — init/2 included — and keeps the result in :persistent_term, so a request only reads a term.

A static repo that isn't started — a script, a Mix task, iex -S mix without the application — still works: its configuration is resolved on every request, with init/2 called as init(:runtime, config). A dynamic instance only exists once started.

The HTTP verbs

A repo exposes request/4 and the verbs over it — get/2, post/3, put/3, patch/3, delete/3 and head/2 — taking a path relative to the endpoint, for any endpoint the API modules don't cover:

MyApp.Search.post("/_plugins/_ml/models/_search", %{query: %{match_all: %{}}})

They go to the process's dynamic repo, and return Dowser.Client.request/4's result ({:ok, %Dowser.Client.Response{}} for any status).

Testing

request/4 is the one place every request goes through, so a mock of this behaviour can stand in for a repo — Mox.defmock(MyApp.SearchMock, for: Dowser.Repo), then repo: MyApp.SearchMock. It returns responses as {:ok, %Dowser.Client.Response{status: 200, body: %{...}}}, and stands in for the whole transport — encoding, decoding and casting included — so the body it returns is exactly what the caller gets. To exercise the casting too, stub the HTTP layer instead (Dowser.Client.HTTP.Stub), behind a real repo.