Test examples/ping-*/README.md

Make examples/ping-*/README.md cram-executable, and test them on every build in Jenkins.

For now let them fail, will revise the policy after example snippets are updated.

.gitignore

@@ -4,3 +4,6 @@ hosts.json
 coverage.out
 lint.log
 /vendor/
+/_venv/
+README.md.err
+tick-cluster.log

.travis.yml

@@ -3,6 +3,11 @@ go:
   - 1.6
   - 1.5
 
+addons:
+  apt:
+    packages:
+    - python-virtualenv
+
 install:
   - go get -u github.com/Masterminds/glide
   - go get github.com/axw/gocov/gocov
@@ -11,17 +16,22 @@ install:
   - go get github.com/golang/lint/golint
   - ./scripts/travis/get-thrift.sh
   - ./scripts/travis/get-thrift-gen.sh
+  - ./scripts/travis/get-cram.sh
+  - npm install -g tcurl
   - make setup
 
 env:
   - RUN="make lint"
   - RUN="make test-unit"
   - RUN="make test-integration"
   - RUN="make test-race"
+  - RUN="make test-examples"
 
 matrix:
   allow_failures:
     - env: RUN="make test-race"
+    - env: RUN="make test-examples"
+
   fast_finish: true
 
 script:
@@ -33,6 +43,7 @@ after_success:
 cache:
   directories:
     - $HOME/.glide/cache
+    - _venv
 
 before_cache:  # glide touches ORIG_HEAD on `glide install`
   - find $HOME/.glide/cache -name ORIG_HEAD -exec rm {} \;

Makefile

@@ -59,16 +59,25 @@ setup: dev_deps
 
 test:	test-unit test-integration
 
-test-integration:
+test-integration: vendor
 	test/run-integration-tests
 
 test-unit:
 	go generate $(NOVENDOR)
 	test/go-test-prettify $(NOVENDOR)
 
-test-race:
+test-examples: vendor _venv/bin/cram
+	. _venv/bin/activate && ./test/run-example-tests
+
+test-race: vendor
 	go generate $(NOVENDOR)
 	test/go-test-prettify -race $(NOVENDOR)
 
+vendor:
+	$(error run 'make setup' first)
+
+_venv/bin/cram:
+	./scripts/travis/get-cram.sh
+
 testpop:	clean
 	go build ./scripts/testpop/

examples/ping-json/README.md

@@ -1,39 +1,36 @@
 A simple ping-pong service implementation that that integrates ringpop to forward requests between nodes.
 
+Note: this file can be [cram][3]-executed using `make test-examples`. That's why some of the example outputs below are a bit unusual.
+
 # Running the example
 
 All commands are relative to this directory:
-```bash
-cd examples/ping-json
-```
 
-Build the example binary:
-```bash
-go build
-```
+    $ cd ${TESTDIR}  # examples/ping-json
+    $ go build
 
 Start a custer of 5 nodes using [tick-cluster][1]:
-```bash
-tick-cluster.js -n 5 ping-json
-```
+
+    $ tick-cluster.js --interface=127.0.0.1 -n 5 ping-json &> tick-cluster.log &
+    $ sleep 5
 
 Lookup the node `my_key` key belongs to using [tcurl][2]:
-```bash
-$ tcurl ringpop -P hosts.json /admin/lookup '{"key": "my_key"}'
-{"ok":true,"head":null,"body":{"dest":"127.0.0.1:3002"},"headers":{"as":"json"},"trace":"88c8217f8ce220fd"}
-```
+
+    $ tcurl ringpop -P hosts.json /admin/lookup '{"key": "my_key"}'
+    {"ok":true,"head":null,"body":{"dest":"127.0.0.1:300?"},"headers":{"as":"json"},"trace":"*"} (glob)
 
 Call the `/ping` endpoint (multiple times) and see the request being forwarded. Each request is sent to a random node in the cluster because of the `-P hosts.json` argument--but is always handled by the node owning the key. This can be seen in the `from` field of the response:
-```bash
-$ tcurl pingchannel -P hosts.json /ping '{"key": "my_key"}'
-{"ok":true,"head":null,"body":{"message":"Hello, world!","from":"127.0.0.1:3002","p":""},"headers":{"as":"json"},"trace":"825d0c582c758aa5"}
-```
+
+    $ tcurl pingchannel -P hosts.json /ping '{"key": "my_key"}'
+    {"ok":true,"head":null,"body":{"message":"Hello, world!","from":"127.0.0.1:300?","p":""},"headers":{"as":"json"},"trace":"*"} (glob)
 
 Optionally, set the `p` header. This value will be forwarded together with the request body to the node owning the key. Its value is returned in the response body in the `pheader` field:
-```bash
-$ tcurl pingchannel -P hosts.json /ping '{"key": "my_key"}' --headers '{"p": "my_header"}'
-{"ok":true,"head":null,"body":{"message":"Hello, world!","from":"127.0.0.1:3002","pheader":"my_header"},"headers":{"as":"json"},"trace":"36b2a16b57b92945"}
-```
+
+    $ tcurl pingchannel -P hosts.json /ping '{"key": "my_key"}' --headers '{"p": "my_header"}'
+    {"ok":true,"head":null,"body":{"message":"Hello, world!","from":"127.0.0.1:300?","pheader":"my_header"},"headers":{"as":"json"},"trace":"*"} (glob)
+
+    $ kill %1
 
 [1]:https://github.com/uber/ringpop-common/
 [2]:https://github.com/uber/tcurl
+[3]:https://pypi.python.org/pypi/cram

examples/ping-thrift-gen/README.md

@@ -1,46 +1,45 @@
 A simple ping-pong service implementation that that integrates ringpop to forward requests between nodes.
 
+Note: this file can be [cram][3]-executed using `make test-examples`. That's why some of the example outputs below are a bit unusual.
+
 This example it's different than the others because it uses ringpop specific generated code to avoid some of the boilerplate.
 
 # Running the example
 
 All commands are relative to this directory:
-```bash
-cd examples/ping-thrift-gen
-```
+
+    $ cd ${TESTDIR}  # examples/ping-thrift-gen
 
 (optional, the files are already included) Generate the thrift code:
-```bash
-thrift-gen --generateThrift --outputDir gen-go --inputFile ping.thrift --template github.com/uber/ringpop-go/ringpop.thrift-gen
-```
+
+    $ thrift-gen --generateThrift --outputDir gen-go --inputFile ping.thrift --template github.com/uber/ringpop-go/ringpop.thrift-gen
 
 Build the example binary:
-```bash
-go build
-```
+
+    $ go build
 
 Start a custer of 5 nodes using [tick-cluster][1]:
-```bash
-tick-cluster.js -n 5 ping-thrift-gen
-```
+
+    $ tick-cluster.js --interface=127.0.0.1 -n 5 ping-thrift-gen &> tick-cluster.log &
+    $ sleep 5
 
 Lookup the node `my_key` key belongs to using [tcurl][2]:
-```bash
-$ tcurl ringpop -P hosts.json /admin/lookup '{"key": "my_key"}'
-{"ok":true,"head":null,"body":{"dest":"127.0.0.1:3002"},"headers":{"as":"json"},"trace":"7a612e506428cec2"}
-```
+
+    $ tcurl ringpop -P hosts.json /admin/lookup '{"key": "my_key"}'
+    {"ok":true,"head":null,"body":{"dest":"127.0.0.1:300?"},"headers":{"as":"json"},"trace":"*"} (glob)
 
 Call the `PingPongService::Ping` endpoint (multiple times) and see the request being forwarded. Each request is sent to a random node in the cluster because of the `-P hosts.json` argument--but is always handled by the node owning the key. This can be seen in the `from` field of the response:
-```bash
-$ tcurl pingchannel -P hosts.json --thrift ./ping.thrift PingPongService::Ping '{"request": {"key": "my_key"}}'
-{"ok":true,"head":{},"body":{"message":"Hello, world!","from_":"127.0.0.1:3002","pheader":""},"headers":{"as":"thrift"},"trace":"650cbf0656e215e2"}
-```
+
+    $ tcurl pingchannel -P hosts.json --thrift ./ping.thrift PingPongService::Ping '{"request": {"key": "my_key"}}'
+    {"ok":true,"head":{},"body":{"message":"Hello, world!","from_":"127.0.0.1:300?","pheader":""},"headers":{"as":"thrift"},"trace":"*"} (glob)
 
 Optionally, set the `p` header. This value will be forwarded together with the request body to the node owning the key. Its value is returned in the response body in the `pheader` field:
-```bash
-$ tcurl pingchannel -P hosts.json /ping '{"key": "my_key"}' --headers '{"p": "my_header"}'
-{"ok":true,"head":{},"body":{"message":"Hello, world!","from_":"127.0.0.1:3002","pheader":"my_header"},"headers":{"as":"thrift"},"trace":"b5526f9625a88347"}
-```
+
+    $ tcurl pingchannel -P hosts.json /ping '{"key": "my_key"}' --headers '{"p": "my_header"}'
+    {"ok":true,"head":{},"body":{"message":"Hello, world!","from_":"127.0.0.1:300?","pheader":"my_header"},"headers":{"as":"thrift"},"trace":"*"} (glob)
+
+    $ kill %1
 
 [1]:https://github.com/uber/ringpop-common/
 [2]:https://github.com/uber/tcurl
+[3]:https://pypi.python.org/pypi/cram

examples/ping-thrift/README.md

@@ -1,44 +1,44 @@
 A simple ping-pong service implementation that that integrates ringpop to forward requests between nodes.
 
+Note: this file can be [cram][3]-executed using `make test-examples`. That's why some of the example outputs below are a bit unusual.
+
 # Running the example
 
 All commands are relative to this directory:
-```bash
-cd examples/ping-thrift
-```
+
+    $ cd ${TESTDIR}  # examples/ping-thrift
 
 (optional, the files are already included) Generate the thrift code:
-```bash
-thrift-gen --generateThrift --outputDir gen-go --inputFile ping.thrift
-```
+
+    $ thrift-gen --generateThrift --outputDir gen-go --inputFile ping.thrift
 
 Build the example binary:
-```bash
-go build
-```
+
+    $ go build
+
 
 Start a custer of 5 nodes using [tick-cluster][1]:
-```bash
-tick-cluster.js -n 5 ping-thrift
-```
+
+    $ tick-cluster.js --interface=127.0.0.1 -n 5 ping-thrift &> tick-cluster.log &
+    $ sleep 5
 
 Lookup the node `my_key` key belongs to using [tcurl][2]:
-```bash
-$ tcurl ringpop -P hosts.json /admin/lookup '{"key": "my_key"}'
-{"ok":true,"head":null,"body":{"dest":"127.0.0.1:3002"},"headers":{"as":"json"},"trace":"7a612e506428cec2"}
-```
+
+    $ tcurl ringpop -P hosts.json /admin/lookup '{"key": "my_key"}'
+    {"ok":true,"head":null,"body":{"dest":"127.0.0.1:300?"},"headers":{"as":"json"},"trace":"*"} (glob)
 
 Call the `PingPongService::Ping` endpoint (multiple times) and see the request being forwarded. Each request is sent to a random node in the cluster because of the `-P hosts.json` argument--but is always handled by the node owning the key. This can be seen in the `from` field of the response:
-```bash
-$ tcurl pingchannel -P hosts.json --thrift ./ping.thrift PingPongService::Ping '{"request": {"key": "my_key"}}'
-{"ok":true,"head":{},"body":{"message":"Hello, world!","from_":"127.0.0.1:3002","pheader":""},"headers":{"as":"thrift"},"trace":"650cbf0656e215e2"}
-```
+
+    $ tcurl pingchannel -P hosts.json --thrift ./ping.thrift PingPongService::Ping '{"request": {"key": "my_key"}}'
+    {"ok":true,"head":{},"body":{"message":"Hello, world!","from_":"127.0.0.1:300?","pheader":""},"headers":{"as":"thrift"},"trace":"*"} (glob)
 
 Optionally, set the `p` header. This value will be forwarded together with the request body to the node owning the key. Its value is returned in the response body in the `pheader` field:
-```bash
-$ tcurl pingchannel -P hosts.json /ping '{"key": "my_key"}' --headers '{"p": "my_header"}'
-{"ok":true,"head":{},"body":{"message":"Hello, world!","from_":"127.0.0.1:3002","pheader":"my_header"},"headers":{"as":"thrift"},"trace":"b5526f9625a88347"}
-```
+
+    $ tcurl pingchannel -P hosts.json /ping '{"key": "my_key"}' --headers '{"p": "my_header"}'
+    {"ok":true,"head":{},"body":{"message":"Hello, world!","from_":"127.0.0.1:300?","pheader":"my_header"},"headers":{"as":"thrift"},"trace":"*"} (glob)
+
+    $ kill %1
 
 [1]:https://github.com/uber/ringpop-common/
 [2]:https://github.com/uber/tcurl
+[3]:https://pypi.python.org/pypi/cram

scripts/travis/get-cram.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+set -e
+
+if [[ ! -f "_venv/bin/activate" ]]; then
+    virtualenv _venv
+fi
+
+. _venv/bin/activate
+
+if [[ -z "$(which cram)" ]]; then
+    ./_venv/bin/pip install cram
+fi

test/lib.sh

@@ -0,0 +1,48 @@
+# Common functions for test code
+
+declare project_root="${0%/*}/.."
+declare ringpop_common_dir="${0%/*}/ringpop-common"
+declare ringpop_common_branch="master"
+
+#
+# Clones or updates the ringpop-common repository.
+# Runs `npm install` in ringpop-common/$1.
+#
+fetch-ringpop-common() {
+    if [ ! -e "$ringpop_common_dir" ]; then
+        run git clone --depth=1 https://github.com/uber/ringpop-common.git "$ringpop_common_dir" --branch "$ringpop_common_branch"
+    fi
+
+    run cd "$ringpop_common_dir"
+    #run git checkout latest version of $ringpop_common_branch
+    run git fetch origin "$ringpop_common_branch"
+    run git checkout "FETCH_HEAD"
+
+    run cd - >/dev/null
+
+    run cd "${ringpop_common_dir}/$1"
+    if [[ ! -d "node_modules" && ! -d "../node_modules" ]]; then
+        run npm install #>/dev/null
+    fi
+    run cd - >/dev/null
+}
+
+#
+# Copy stdin to stdout but prefix each line with the specified string.
+#
+prefix() {
+    local _prefix=
+
+    [ -n "$1" ] && _prefix="[$1] "
+    while IFS= read -r -t 30 line; do
+        echo "${_prefix}${line}"
+    done
+}
+
+#
+# Echos and runs the specified command.
+#
+run() {
+    echo "+ $@" >&2
+    "$@"
+}