Etcd Watcher for Play
What is play-etcd-watcher?
play-etcd-watcher is a library to listen for changes in etcd via its REST interface and notify the client application through its listeners.
Target users
You develop a Scala/Play service and at some point you need to change configuration parameters, e.g. feature toggle. Would you redeploy your application with a new parameter? Or maybe you change the source code? If this sounds familiar but you want to avoid such hassles, then you probably need some kind of configuration service, e.g. key-value store. If you use etcd, then play-etcd-watcher
will help to listen for key changes in your application.
Key features
The updates are received by the client application instantaneous due to the implemented long polling. After an error, the connection is tried again after the timeout (defaults to 10 seconds). In normal operation the connection is re-established after a period of time (defaults to 90 seconds).
Getting started
Add play-etcd-watcher dependency to your build.sbt
:
libraryDependencies += Seq(
"org.zalando" %% "play-etcd-watcher" % "2.6.0"
)
Add the module to conf/application.conf
:
play.modules.enabled += "org.zalando.etcdwatcher.EtcdWatcherModule"
and specify the following config parameters:
etcd {
url = http://my-etcd.url
directory = /my/etcd/directory
}
where etcd.url
denotes the etcd url and etcd.directory
denotes the directory being watched. The directory will be scanned recursively.
Next, implement the listener trait:
trait ConfigListener {
def keysUpdated(keyValues: Map[String, Option[String]]): Unit
}
and bind it to the implementation in your Module, e.g.
class AppModule extends AbstractModule with ScalaModule {
override def configure(): Unit = {
...
bind[ConfigListener].to[MyConfigListener]
}
}
The method will be called on startup and on each key change. The Option
value of None
denotes the deletion of the key.
Versioning
The version number follows the Play version but does not necessarily correspond to its minor version. As an example, if the first release of play-etcd-watcher
was made for Play 2.5.4
, the version would be 2.5.0
.
Developer notes
Releasing artifacts to nexus
Prerequisites
To deploy the artifact to nexus you need to have the following prerequisites:
- Sonatype account
- Rights for the corresponding repository
- Your pgp key to sign the artifact
Deployment procedure
See this page for more documentation. We use sbt-sonatype
and sbt-pgp
plugins to take care of deployment. To deploy, run the following commands: git clean -df sbt publishSigned sbt sonatypeRelease
IF the last step fails with an error like this:
[error] Multiple repositories are found:
[error] [orgzalando-1999] status:open, profile:org.zalando(6cc4d987a65f6) description: Implicitly created (auto staging).
[error] [orgzalando-2009] status:open, profile:org.zalando(6cc4d987a65f6) description: Implicitly created (auto staging).
[error] Specify one of the repository ids in the command line
then you may need to specify the id explicitly:
sbt "sonatypeRelease orgzalando-2009"
Most probably profileId
is that the last in the list but check staging repositories (you need to be logged in).
Have fun!
License
The MIT License (MIT)
Copyright (c) 2016 Zalando SE
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.