og_ex

# Function Reference

This reference covers every function implemented by the OgEx Elixir library and
Takumi NIF. Public functions also have ExDoc documentation in their source
modules. Private functions are documented here because ExDoc intentionally
excludes private APIs.

## `OgEx`

- `init/1` — initializes the optional backward-compatible endpoint plug.
- `call/2` — eagerly fetches query parameters for applications that retain the
  optional plug; new applications do not need it.

## Application internals (`OgEx.Application`)

- `start/2` — starts the OgEx supervisor and its default ETS cache.

## `OgEx.Card`

- `__using__/1` — imports Phoenix component functionality, installs the card
  behaviour, and records width, height, and output format.
- generated `__og_ex__/1` — returns the configured `:width`, `:height`, or
  `:format` for a card module.
- callback `metadata/1` — returns page and image metadata for the current
  assigns.
- callback `render/1` — returns the card's HEEx safe data.
- optional callback `version/1` — returns stable content data used for the image
  URL, ETag, and cache key.

## `OgEx.Controller`

- `__using__/1` — installs a controller-local OgEx-aware `render/3`.
- generated `render/3` — forwards the consuming controller's render request to
  `OgEx.Controller.render/3`.
- `render/3` — delegates ordinary renders to Phoenix; for an OgEx card, selects
  either the normal page response or signed image response and discovers the
  signature lazily.
- private `pop_card/1` — separates the `:og` card module from keyword-list or
  map template assigns.

## Configuration builder internals (`OgEx.ConfigBuilder`)

- `build/3` — evaluates metadata, creates the deterministic content version and
  compact 22-character HMAC, and returns a complete `%OgEx.Config{}`.
- `verify/2` — rebuilds and securely compares the signature bound to the card,
  version, and request path.
- private `version/2` — hashes the card identity and either `version/1` output
  or full assigns into a URL-safe SHA-256 value.
- private `signature/3` — creates a 128-bit truncated HMAC.
- private `signing_key/1` — derives a domain-separated key from Phoenix's
  `secret_key_base`.
- private `image_url/2` — adds the compact signature to the current absolute URL
  while preserving unrelated query parameters.

## Request internals (`OgEx.Request`)

- `image_request?/1` — lazily reports whether the reserved signature is present.
- `signature/1` — lazily fetches and returns the signature, or `nil`.

## HTML internals (`OgEx.HTML`)

- `render/1` — evaluates card HEEx safely and wraps it in a complete,
  viewport-sized HTML document for the native renderer.

## `OgEx.Renderer`

- callback `render/2` — converts HTML plus rendering options into an encoded
  image binary.

## `OgEx.Renderer.Takumi`

- `render/2` — normalizes Elixir keyword options and invokes the native Takumi
  renderer.

## Native bridge internals (`OgEx.Native`)

- `render_html/2` — Rustler NIF declaration. Its Elixir body raises
  `:nif_not_loaded` only if native loading failed.

## Font internals (`OgEx.Fonts`)

- `load/0` — resolves every configured path or binary into loaded font bytes.
- private `load_font!/1` — reads an existing path; otherwise treats the input
  as an already-loaded binary.

## Image response internals (`OgEx.ImageResponse`)

- `send/2` — verifies the request, obtains the encoded image, and sends the
  correct immutable HTTP response.
- private `cached_or_render/1` — checks the configured cache and executes the
  HTML/native rendering pipeline on a miss.
- private `render/2` — loads fonts, calls the configured renderer, and emits
  successful-render telemetry.
- private `content_type/1` — maps `:png`, `:jpeg`, `:webp`, and `:svg` to their
  HTTP media types.

## `OgEx.Cache`

- callback `fetch/1` — follows `Map.fetch/2`, returning `{:ok, image}` when
  found or `:error` when absent.
- callback `put/2` — stores an encoded image.

## `OgEx.Cache.ETS`

- `start_link/1` — starts the cache table owner.
- `fetch/1` — performs a concurrent direct ETS lookup and returns
  `{:ok, image}` or `:error`.
- `put/2` — inserts or replaces an ETS cache entry.
- `init/1` — creates the named, concurrent-read ETS table.

## Head injection internals (`OgEx.Head`)

- `put_config/2` — assigns the card configuration and registers metadata
  injection before the response is sent.
- private `inject_metadata/1` — rewrites complete binary HTML responses and
  leaves unsupported response shapes unchanged.
- private `replace_closing_head/2` — inserts tags before the first
  case-insensitive `</head>` without changing the rest of the original bytes.

## Metadata internals (`OgEx&#46;Meta`)

- `to_html/1` — builds the complete escaped Open Graph and Twitter/X tag set.
- private `meta/1` — safely encodes one `<meta>` element.
- private `optional_meta/2` — omits absent values or adds a `content` attribute
  and delegates to `meta/1`.

## Native Rust functions

These functions live in `native/og_ex_native/src/lib.rs`.

- `render_html/3` — exported dirty-CPU NIF. It decodes Elixir arguments, calls
  the native pipeline, and returns `{:ok, binary}` or `{:error, reason}`.
- private `render/2` — parses HTML, parses CSS, registers fonts, runs Takumi
  layout and painting, and encodes the resulting bitmap.
- private `extract_stylesheets/1` — extracts card-local `<style>` contents
  because Takumi's HTML helper discards style elements from the node tree.
- private `output_format/1` — maps raster Elixir atoms to Takumi encoder
  settings; SVG bypasses raster encoding and uses Takumi's vector backend.