gnat
gnat v1.9.0

View Source Gnat.Services.Server behaviour (gnat v1.9.0)

A behavior for acting as a NATS service

Creating a service with this behavior works almost exactly the same as Gnat.Server, with the bonus that this service keeps track of requests, errors, processing time, and participates in service discovery and monitoring as defined by the NATS service protocol.

Example 

defmodule MyApp.Service do
  use Gnat.Services.Server

  # Classic subject matching
  def request(%{body: _body, topic: "myservice.req"}, _, _) do
    {:reply, "handled request"}
  end

  # Can also match on endpoint or group
  def request(msg, "add", "calculator") do
    {:reply, "42"}
  end

  # defining an error handler is optional, the default one will just call Logger.error for you
  def error(%{gnat: gnat, reply_to: reply_to}, _error) do
    Gnat.pub(gnat, reply_to, "Something went wrong and I can't handle your request")
  end
end

Link to this section Summary

Types

endpoint_configuration()

Each service configuration must contain at least one endpoint. Endpoints can manually specify their subscription subjects or they can be derived from the endpoint name.

service_configuration()

Service configuration is provided as part of the consumer supervisor settings in the service_definition field. You can specify either the subscription_topics field for a regluar server or the service_definition field for a new NATS service.

Callbacks

error(message, error)

Called when an error occured during the request/1. Automatically increments the error count and processing time stats for this service.

request(message, endpoint, group)

Called when a message is received from the broker. The endpoint on which the message arrived is always supplied. If the endpoint is a member of a group, the group name will also be provided.

Link to this section Types

Link to this type

endpoint_configuration()

View Source

Specs

endpoint_configuration() :: %{
  :name => binary(),
  optional(:subject) => binary(),
  optional(:group_name) => binary(),
  optional(:queue_group) => binary(),
  optional(:metadata) => map()
}

Each service configuration must contain at least one endpoint. Endpoints can manually specify their subscription subjects or they can be derived from the endpoint name.

  • subject - A specific subject for this endpoint to listen on. If this is not provided, then the endpoint name will be used.
  • name - The required name of the endpoint
  • group_name - An optional group to which this endpoint belongs
  • queue_group - A queue group for this endpoint's subscription. If not supplied, "q" will be used (indicated by protocol spec).
  • metadata - An optional string->string map containing metadata for this endpoint
Link to this type

service_configuration()

View Source

Specs

service_configuration() :: %{
  :name => binary(),
  :version => binary(),
  :endpoints => [endpoint_configuration()],
  optional(:description) => binary(),
  optional(:metadata) => map()
}

Service configuration is provided as part of the consumer supervisor settings in the service_definition field. You can specify either the subscription_topics field for a regluar server or the service_definition field for a new NATS service.

  • name - The name of the service. Needs to conform to the rules for NATS service names
  • version - A required version number (w/out "v" prefix) conforming to semver rules
  • queue_group - An optional queue group for service subscriptions. If left off, "q" will be used.
  • description - An optional description of the service
  • metadata - An optional string->string map of service metadata
  • endpoints - A required list of service endpoints. All services must have at least one endpoint

Link to this section Callbacks

Link to this callback

error(message, error)

View Source

Specs

error(message :: Gnat.message(), error :: term()) :: :ok | {:reply, iodata()}

Called when an error occured during the request/1. Automatically increments the error count and processing time stats for this service.

If your request/1 function returned {:error, term}, then the term you returned will be passed as the second argument. If an exception was raised during your request/1 function, then the exception will be passed as the second argument. If your request/1 function returned something other than the supported return types, then its return value will be passed as the second argument.

Link to this callback

request(message, endpoint, group)

View Source

Specs

request(
  message :: Gnat.message(),
  endpoint :: String.t(),
  group :: String.t() | nil
) ::
  :ok | {:reply, iodata()} | {:error, term()}

Called when a message is received from the broker. The endpoint on which the message arrived is always supplied. If the endpoint is a member of a group, the group name will also be provided.

Automatically increments the request time and processing time stats for this service.