Processes the request to identify and set the tenant context.

This is the main plug function that executes for each request. It implements a comprehensive tenant resolution pipeline including domain extraction, site lookup, validation, and context setting for downstream processing.

Parameters

• conn - Plug.Conn struct representing the HTTP request/response
• opts - Configuration options from init/1

Return Value

• Plug.Conn - Updated connection with tenant context or error response

Processing Pipeline

1. Host Extraction: Extracts domain from Host header or conn.host (tests)
2. Site Lookup: Queries SiteState cache for site configuration
3. Site Validation: Ensures site is active and available
4. Tenant Override Check: Handles explicit no-tenant requests
5. Context Setting: Configures Ash tenant context and response headers
6. Assignment: Sets current_site assign for controller access

Successful Flow

# Request: GET /api/posts
# Header: Host: blog.example.com

# 1. Extract host: "blog.example.com"
# 2. Lookup site: %Site{id: 42, host: "blog.example.com", active: true}
# 3. Validate: site active ✓
# 4. Check override: no x-no-tenant header ✓
# 5. Set tenant context: Ash.set_tenant(42)
# 6. Add headers: x-tenant-id: "42"
# 7. Assign: conn.assigns.current_site = %Site{...}

Error Handling

The function handles multiple error scenarios:

# Missing Host header
# Result: 400 with detailed JSON error (if allow_no_tenant: false)
# Result: current_site: nil (if allow_no_tenant: true)

# Unknown domain
# Result: 404 with detailed JSON error (if allow_no_tenant: false)
# Result: current_site: nil (if allow_no_tenant: true)

# Inactive site
# Result: 503 with "website_unavailable" error (always)

Examples

# Standard tenant request
conn = %Plug.Conn{
  req_headers: [$("host", "mysite.com")]
}

updated_conn = ApiTenantLookupPlug.call(conn, allow_no_tenant: false)
# Result: conn.assigns.current_site = %Site{id: 123, host: "mysite.com"}
# Headers: x-tenant-id: "123"

# The master accounts' switch, on the master site's address
conn = %Plug.Conn{
  req_headers: [
    $("host", "master.example.com"),
    $("x-no-tenant", "true")
  ]
}

updated_conn = ApiTenantLookupPlug.call(conn, [])
# Result: conn.assigns.current_site = %Site{master: true, ...}
# Headers: x-tenant-id: "none"
# Ash tenant context: nil
# On any other site's address: x-tenant-id is the site's id, and so is the tenant

Integration with Controllers

defmodule MyAppWeb.Api.PostController do
  def index(conn, _params) do
    site = conn.assigns.current_site

    if site do
      # Tenant-specific posts (Ash context set automatically)
      posts = MyApp.Blog.list_posts!()
      render(conn, :index, posts: posts)
    else
      # Global posts (no tenant context)
      posts = MyApp.Blog.list_all_posts!()
      render(conn, :global_index, posts: posts)
    end
  end
end

Monitoring and Debugging

# Add custom telemetry
defmodule TenantLookupTelemetry do
  def track_tenant_resolution(conn, result) do
    :telemetry.execute(
      [:api, :tenant_lookup],
      %{duration: processing_time},
      %{
        host: get_req_header(conn, "host") |> List.first(),
        result: result,
        tenant_id: conn.assigns[:current_site] && conn.assigns.current_site.id
      }
    )
  end
end

Security Considerations

# The plug automatically prevents:
# - Cross-tenant data access (via Ash context)
# - Inactive site access (503 responses)
# - Malformed host header attacks (validation)

# Additional security can be layered:
plug ApiTenantLookupPlug
plug TenantRateLimitPlug
plug TenantPermissionPlug

@spec confirm_bearer_tenant(Plug.Conn.t(), term()) :: Plug.Conn.t()

Confirms the tenant call/2 chose, once :load_from_bearer has read the token's user.

Plug it in straight after :load_from_bearer, imported from this module:

import MishkaCmsCore.Runtime.Plugs.ApiTenantLookupPlug, only: [confirm_bearer_tenant: 2]

pipeline :api do
  plug MishkaCmsCore.Runtime.Plugs.ApiTenantLookupPlug
  # ...
  plug :load_from_bearer
  plug :confirm_bearer_tenant
  plug :set_actor, :user
end

An unscoped request is a master's, a user whose site_id is nil, or nobody's. Anyone else on an unscoped request — a user with a site holding a token issued with no site, or an actor that carries no site_id at all — is nobody: :current_user becomes nil, and a plugin on api:request:token_refused hears it with %{site: site, user_id: id}.

A user the site's closed sign-in signs out (MishkaCmsCore.Accounts.AuthGate.signs_out?/2) is signed out everywhere and is nobody too.

Initializes the plug with configuration options.

This function merges user-provided options with default settings to configure the plug's behavior. It's called once when the plug is compiled into the router pipeline, not on each request.

Parameters

• opts - Keyword list of configuration options:
  • :allow_no_tenant - Boolean, lets a request from a missing or unknown host go on with no tenant, where only a master is recognised (defaults to false)

Return Value

Returns merged configuration that will be passed to call/2 function.

Examples

# Default configuration
plug MishkaCmsCore.Runtime.Plugs.ApiTenantLookupPlug
# Equivalent to: plug ..., allow_no_tenant: false

# Let a request from a missing or unknown host go on unscoped
plug MishkaCmsCore.Runtime.Plugs.ApiTenantLookupPlug, allow_no_tenant: true

Configuration Options

:allow_no_tenant

When true:

• Missing host headers result in current_site: nil
• Unknown domains result in current_site: nil
• Such a request goes on unscoped, with no tenant

It gives nobody more reach. On an unscoped request confirm_bearer_tenant/2 drops every user with a site, so only a master (a user whose site_id is nil) is recognised there — and a master's token then works from any unknown host, not only from the master site's address. It passes over that master-site-only rule, so leave it off unless an endpoint needs exactly that.

When false (default):

• Missing host headers return 400 "missing_host" error
• Unknown domains return 404 "domain_not_found" error
• Requests are halted with detailed error responses
• Enforces strict tenant isolation

Use Cases by Configuration

# Every request scoped to the site its host names
pipeline :tenant_api do
  plug MishkaCmsCore.Runtime.Plugs.ApiTenantLookupPlug  # allow_no_tenant: false
end

# A request from no known host goes on unscoped; only a master is recognised on it
pipeline :unscoped_api do
  plug MishkaCmsCore.Runtime.Plugs.ApiTenantLookupPlug, allow_no_tenant: true
end