OgEx.Image (og_ex v0.2.0)

Copy Markdown View Source

Normalizes and loads image sources.

Accepted source forms:

  • "/images/card.png" for a file below the host application's priv/static
  • "https://cdn.example.com/card.webp" for a remote image
  • "data:image/png;base64,..." inside a generated card
  • {:private, "reports/card.png"} in direct controller metadata
  • private_asset/1 inside generated-card HEEx

Most applications use source values in controller declarations or HEEx rather than calling this module directly. Custom resource loaders can use normalize/2 and load/2 at the same boundary as the built-in loader.

See the README for rendered examples of public and remote sources embedded in a generated card and a public file used directly as og:image.

Summary

Functions

content_type(atom)

Returns the HTTP media type for a verified image format.

load(source, options \\ [])

Loads and verifies a normalized source through the configured loader.

normalize(path, conn)

Normalizes a supported image reference.

otp_app(conn)

Returns the OTP application that owns the connection's Phoenix endpoint.

private_asset(path)

Builds an opaque source string for a private image inside card HEEx.

public_url(conn, path)

Converts a root-relative static path into an absolute endpoint URL.

Functions

content_type(atom)

Returns the HTTP media type for a verified image format.

load(source, options \\ [])

Loads and verifies a normalized source through the configured loader.

options are passed to the loader. The default loader returns {:ok, %OgEx.Image.Resource{}} or a structured error. Remote sources require remote_images: [enabled: true, ...].

The function emits [:og_ex, :resource, :stop] for success and failure.

normalize(path, conn)

Normalizes a supported image reference.

Local paths are resolved below their trusted root and rejected when missing, unreadable, absolute, traversing, or symlinked. The return value is {:ok, source} or {:error, reason}.

otp_app(conn)

Returns the OTP application that owns the connection's Phoenix endpoint.

When it cannot be inferred, this reads config :og_ex, otp_app: ... and raises ArgumentError if no application is configured.

private_asset(path)

Builds an opaque source string for a private image inside card HEEx.

The path is resolved below the configured :private_asset_root; it is never exposed to Takumi as a filesystem path.

public_url(conn, path)

Converts a root-relative static path into an absolute endpoint URL.

If the endpoint exports static_path/1, its cache-digested path is used.