Pulse

Service registration and discovery library for Elixir. Relies on etcd as an external service registry.

Works best with FQDN node names, such as [email protected].

Installation

The latest version is 0.1.0 and requires Elixir ~> 1.2. New releases may change this minimum compatible version depending on breaking language changes. The changelog lists every available release and its corresponding language version requirement.

Releases are published through hex.pm. Add as a dependency in your mix.exs file:

defp deps do
  [ { :pulse, "~> 0.1" } ]
end

Also ensure it's listed in the mix.exs list of applications to start:

def application do
  [
    applications: [:pulse]
  ]
end

Configuration

Below is the complete default configuration. All parameters can be changed.

config :pulse,
  directory: "pulse"

For etcd connection configuration, see Sonic.

Usage

There are three discrete functions handled by Pulse:

• Service Registration - Publishing service status so it is discoverable by other nodes.
• Service Discovery - Retrieving a list of available nodes registered to provide a service.
• Service Directory - Maintaining the internal service registry and handling connections to discovered nodes.

For the examples below, we'll assume a typical Application module with a start function:

def start(_type, _args) do
import Supervisor.Spec, warn: false

children = [
  worker(MyApp.SomeWorker, [])
]

opts = [strategy: :one_for_one, name: MyApp.Supervisor]
Supervisor.start_link(children, opts)
end

Service Registration

Pulse.Register is responsible for service registration. To use it, declare it as a worker in your application's supervision tree.

The module takes 4 parameters in a keyword list, for legibility:

• service - A binary indicating the service name to register.
• ttl - An integer indicating the number of seconds the registration should live unless refreshed.
• heartbeat - An integer indicating the number of seconds to wait between registration refreshes.
• delay - An integer indicating the number of seconds to wait before first registration.

children = [
  worker(Pulse.Register, [[service: "my_service", ttl: 15, heartbeat: 5, delay: 5]])
]

Each Pulse.Register worker is only responsible for one service, but you can register the application as providing multiple services by declaring more than one worker.

children = [
  worker(Pulse.Register, [[service: "my_service", ttl: 15, heartbeat: 5, delay: 5]], id: MyApp.MyServiceRegister),
  worker(Pulse.Register, [[service: "my_other_service", ttl: 15, heartbeat: 5, delay: 5]], id: MyApp.MyOthereSrviceRegister)
  # ...
]

The configuration options should be tuned for your application, however the values shown above are a good baseline.

Service Discovery

Start one or more Pulse.Discover workers to look up registered nodes for required services.

The module taks 3 parameters in a keyword list, for legibility:

• service - A binary indicating the service name to discover.
• poll - An integer indicating the number of seconds to wait between discovery refreshes.
• delay - An integer indicating the number of seconds to wait before first discovery.

children = [
  worker(Pulse.Discover, [[service: "my_service", poll: 5, delay: 1]])
]

Each Pulse.Discover worker is only responsible for one service, but you can discover multiple services by declaring more than one worker.

children = [
  worker(Pulse.Discover, [[service: "my_service", poll: 5, delay: 1]], id: MyApp.MyServiceDiscover),
  worker(Pulse.Discover, [[service: "my_other_service", poll: 5, delay: 1]], id: MyApp.MyOtherServiceDiscover)
  # ...
]

The configuration options should be tuned for your application, however the values shown above are a good baseline.

Service Directory

The Pulse.Directory module maintains connections and tracks available nodes registered for each discovered service. This module is monitored by Pulse internally, you do not need to start a worker to use it.

Pulse.Directory.get/1 is the primary way to retrieve available nodes for any given discovered service.

iex> Pulse.Directory.get("my_service")
[:"[email protected]", :"[email protected]"]

These nodes will already be connected by the Pulse.Directory process and are valid RPC targets if necessary. The directory also monitors connections and will unregister nodes from service lists if they disconnect.

License

Copyright 2016 Heroic Labs

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.