A parsed view of a single message from a Key/Value bucket's underlying stream.

Messages delivered from a KV bucket's stream encode three different operations (put, delete, purge) using a combination of the kv-operation header, the nats-marker-reason header, and the absence of any headers. Recovering the original key also requires stripping the $KV.<bucket>. subject prefix.

This module captures that convention in one place so both the built-in Gnat.Jetstream.API.KV.Watcher (push consumer) and user-supplied Gnat.Jetstream.PullConsumer implementations can share it.

Using with a custom PullConsumer

A common use case is hydrating a local cache from a KV bucket by driving a Gnat.Jetstream.PullConsumer. Inside c:handle_message/2, convert the raw message into an Entry and branch on the operation:

defmodule MyApp.KVCache do
  use Gnat.Jetstream.PullConsumer

  alias Gnat.Jetstream.API.KV

  @bucket "my_bucket"

  @impl true
  def handle_message(message, state) do
    case KV.Entry.from_message(message, @bucket) do
      {:ok, %KV.Entry{operation: :put, key: key, value: value}} ->
        {:ack, put_in(state.cache[key], value)}

      {:ok, %KV.Entry{operation: op, key: key}} when op in [:delete, :purge] ->
        {:ack, update_in(state.cache, &Map.delete(&1, key))}

      :ignore ->
        {:ack, state}
    end
  end
end

The returned struct also carries the JetStream revision (stream sequence), created timestamp, and delta (num_pending) when the message includes JetStream metadata, which is useful for detecting when the consumer has caught up with the tail of the stream (delta == 0).

Messages that are not KV records

from_message/2 returns :ignore when the input is not a KV record — for example a JetStream status message (100 heartbeat, 404/408 pull terminator, 409 leadership change) or a message whose subject does not belong to the given bucket. In normal operation the Watcher and PullConsumer layers filter status messages out before they reach user code, so this is a defensive fallback rather than something consumers are expected to rely on.