View Source Polyn.PullConsumer behaviour (Polyn v0.6.3)

Use Polyn.PullConsumer to connect and process messages from an existing NATS Consumer that was setup with Polyn CLI. This module is a wrapper around Jetstream.PullConsumer that does schema validation with the received messages. A key difference that Polyn adds is that the :consumer_name will be taken care of for you by using the passed type and configured :source_root. You can pass :source to start_link/3 to get a more specific :consumer_name. This type of Consumer is meant for simple use cases that don't involve concurrency or batching.

example

Example

defmodule MyApp.PullConsumer do
  use Polyn.PullConsumer

  def start_link(arg) do
    Polyn.PullConsumer.start_link(__MODULE__, arg,
      connection_name: :gnat,
      type: "user.created.v1")
  end

  @impl true
  def init(_arg) do
    {:ok, nil}
  end

  @impl true
  def handle_message(message, state) do
    # Do some processing with the message.
    {:ack, state}
  end
end

Link to this section Summary

Types

Options for starting a Polyn.PullConsumer

Callbacks

Invoked to synchronously process a message pulled by the consumer. Depending on the value it returns, the acknowledgement is or is not sent. Polyn will deserialize the message body into a Polyn.Event struct and use that as the first argument, followed by the original message, follwed by the state.

Invoked when the server is started. start_link/3 or start/3 will block until it returns.

Functions

Returns a specification to start this module under a supervisor.

Closes the pull consumer and stops underlying process.

Starts a Jetstream.PullConsumer process without links (outside of a supervision tree).

Starts a pull consumer linked to the current process with the given function.

Link to this section Types

@type option() ::
  {:type, binary()}
  | {:source, binary()}
  | {:connection_name, Gnat.t()}
  | {:stream_name, binary()}
  | GenServer.option()

Options for starting a Polyn.PullConsumer

  • :type - Required. The event type to consume
  • :connection_name - Required. The Gnat connection identifier
  • :source - Optional. More specific name for the consumer to add to the :source_root
  • :stream_name - Optional. Choose a specific stream name not derived from the type
  • All other options will be assumed to be GenServer options

Link to this section Callbacks

Link to this callback

handle_message(event, message, state)

View Source
@callback handle_message(
  event :: Polyn.Event.t(),
  message :: Jetstream.message(),
  state :: term()
) :: {ack_action, new_state}
when ack_action: :ack | :nack | :term | :noreply, new_state: term()

Invoked to synchronously process a message pulled by the consumer. Depending on the value it returns, the acknowledgement is or is not sent. Polyn will deserialize the message body into a Polyn.Event struct and use that as the first argument, followed by the original message, follwed by the state.

ack-actions

ACK actions

See Jetstream.PullConsumer.handle_message/2 for available options

example

Example

def handle_message(event, _message, state) do
  IO.inspect(event)
  {:ack, state}
end
@callback init(init_arg :: term()) ::
  {:ok, state :: term()} | :ignore | {:stop, reason :: any()}

Invoked when the server is started. start_link/3 or start/3 will block until it returns.

init_arg is the argument term (second argument) passed to start_link/3.

See Connection.init/1 for more details.

Link to this section Functions

@spec child_spec(arg :: GenServer.options()) :: Supervisor.child_spec()

Returns a specification to start this module under a supervisor.

See the "Child specification" section in the Supervisor module for more detailed information.

@spec close(consumer :: Jetstream.PullConsumer.consumer()) :: :ok

Closes the pull consumer and stops underlying process.

example

Example

{:ok, consumer} =
  PullConsumer.start_link(ExamplePullConsumer, %{initial_arg: "foo"},
    connection_name: :gnat,
    type: "user.updated.v1",
    stream: "TEST_STREAM",
  )

:ok = PullConsumer.close(consumer)
Link to this function

start(module, init_arg, opts \\ [])

View Source
@spec start(module(), init_arg :: term(), options :: [option()]) ::
  GenServer.on_start()

Starts a Jetstream.PullConsumer process without links (outside of a supervision tree).

See start_link/3 for more information.

Link to this function

start_link(module, init_arg, opts \\ [])

View Source
@spec start_link(module(), init_arg :: term(), options :: [option()]) ::
  GenServer.on_start()

Starts a pull consumer linked to the current process with the given function.

This is often used to start the pull consumer as part of a supervision tree.

Once the server is started, the init/1 function of the given module is called with init_arg as its argument to initialize the server. To ensure a synchronized start-up procedure, this function does not return until init/1 has returned.

See GenServer.start_link/3 for more details.

example

Example

{:ok, consumer} =
  Polyn.PullConsumer.start_link(ExamplePullConsumer, %{initial_arg: "foo"},
    connection_name: :gnat,
    type: "user.updated.v1",
    stream: "TEST_STREAM",
  )