SferaDoc.Pdf.ObjectStore.Adapter behaviour (sfera_doc v0.1.0)

Copy Markdown View Source

Behaviour that all SferaDoc PDF object-storage adapters must implement.

Object storage is the durable source of truth for rendered PDFs. Adapters persist PDF binaries keyed by {name, version, assigns_hash} so that identical renders survive BEAM restarts without re-invoking Chrome.

Implementing a Custom Adapter

  1. @behaviour SferaDoc.Pdf.ObjectStore.Adapter

  2. Implement all callbacks

  3. Return nil from worker_spec/0 if your adapter manages its own connections externally (e.g. HTTP-based S3/Azure clients)

  4. Configure the library to use your adapter:

    config :sfera_doc, :pdf_object_store,
  adapter: MyApp.CustomAdapter,
  my_option: "value"

Summary

Types

assigns_hash()
name()
reason()
version()

Callbacks

get(name, version, assigns_hash)

Retrieves a stored PDF binary. Returns {:ok, binary} on hit, :miss if the object does not exist, or {:error, reason} on storage failure (treated as :miss).

put(name, version, assigns_hash, binary)

Persists a rendered PDF binary. Returns :ok on success or {:error, reason} on failure. Failures are logged but do not abort the render pipeline.

worker_spec()

Returns a child spec for processes this adapter needs, or nil if the adapter manages its own connections (e.g. HTTP-based clients).

Types

assigns_hash()

@type assigns_hash() :: String.t()

name()

@type name() :: String.t()

reason()

@type reason() :: any()

version()

@type version() :: pos_integer()

Callbacks

get(name, version, assigns_hash)

@callback get(name(), version(), assigns_hash()) ::
  {:ok, binary()} | :miss | {:error, reason()}

Retrieves a stored PDF binary. Returns {:ok, binary} on hit, :miss if the object does not exist, or {:error, reason} on storage failure (treated as :miss).

put(name, version, assigns_hash, binary)

@callback put(name(), version(), assigns_hash(), binary()) :: :ok | {:error, reason()}

Persists a rendered PDF binary. Returns :ok on success or {:error, reason} on failure. Failures are logged but do not abort the render pipeline.

worker_spec()

@callback worker_spec() :: Supervisor.child_spec() | nil

Returns a child spec for processes this adapter needs, or nil if the adapter manages its own connections (e.g. HTTP-based clients).