gorouter

command module
v0.0.0-...-b7aefed Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 25, 2014 License: Apache-2.0, BSD-2-Clause-Views, BSD-3-Clause, + 1 more Imports: 17 Imported by: 0

README

Build Status

gorouter

This repository contains the source code for a Go implementation of the Cloud Foundry router.

This router is now used on CloudFoundry.com, replacing the old implementation.

Summary

The original router can be found at cloudfoundry/router. The original router is backed by nginx, that uses Lua code to connect to a Ruby server that -- based on the headers of a client's request -- will tell nginx which backend it should use. The main limitations in this architecture are that nginx does not support non-HTTP (e.g. traffic to services) and non-request/response type traffic (e.g. to support WebSockets), and that it requires a round trip to a Ruby server for every request.

The Go implementation of the Cloud Foundry router is an attempt in solving these limitations. First, with full control over every connection to the router, it can more easily support WebSockets, and other types of traffic (e.g. via HTTP CONNECT). Second, all logic is contained in a single process, removing unnecessary latency.

Getting started

The following instructions may help you get started with gorouter in a standalone environment.

External Dependencies
Development Setup

Download gorouter:

go get -v github.com/cloudfoundry/gorouter
cd $GOPATH/src/github.com/cloudfoundry/gorouter

To install exactly the dependecies vendored with gorouter, use godep:

go get -v github.com/tools/godep
godep restore ./...
Running Tests

We are using Ginkgo, to run tests.

Running scripts/test will:

  • Check for Go
  • Check that GOPATH is set
  • Download & Install gnatsd (or use the one already downloaded into the GOPATH)
  • Update the PATH to prepend the godep workspace
  • Install ginkgo (from the godep vendored sources into the godep workspace bin)
  • Run all the tests with ginkgo (in random order, without benchmarks, using the vendored godep dependencies)

Any flags passed into scripts/test will be passed into ginkgo.

# run all the tests
scripts/test

# run only tests whose names match Registry
scripts/test -focus=Registry

# run only the tests in the registry package
scripts/test registry

To run the tests using GOPATH dependency sources (bypassing vendored dependencies):

ginkgo -r
Building

Building creates an executable in the gorouter/ dir:

go build
Installing

Installing creates an executable in the $GOPATH/bin dir:

go install
Start
# Start NATS server in daemon mode
go get github.com/apcera/gnatsd
gnatsd &

# Start gorouter
gorouter
Usage

When gorouter starts, it sends router.start. This message contains an interval that other components should then send router.register on. If they do not send a router.register for an amount of time considered "stale" by the router, the routes are pruned. The default "staleness" is 2 minutes.

The format of this message is as follows:

{
  "id": "some-router-id",
  "hosts": ["1.2.3.4"],
  "minimumRegisterIntervalInSeconds": 5
}

If a component comes online after the router, it must make a NATS request called router.greet in order to determine the interval. The response to this message will be the same format as router.start.

The format of route updates are as follows:

{
  "host": "127.0.0.1",
  "port": 4567,
  "uris": [
    "my_first_url.vcap.me",
    "my_second_url.vcap.me"
  ],
  "tags": {
    "another_key": "another_value",
    "some_key": "some_value"
  }
}

Such a message can be sent to both the router.register subject to register URIs, and to the router.unregister subject to unregister URIs, respectively.

$ nohup ruby -rsinatra -e 'get("/") { "Hello!" }' &
$ nats-pub 'router.register' '{"host":"127.0.0.1","port":4567,"uris":["my_first_url.vcap.me","my_second_url.vcap.me"],"tags":{"another_key":"another_value","some_key":"some_value"}}'
Published [router.register] : '{"host":"127.0.0.1","port":4567,"uris":["my_first_url.vcap.me","my_second_url.vcap.me"],"tags":{"another_key":"another_value","some_key":"some_value"}}'
$ curl my_first_url.vcap.me:8080
Hello!
Instrumentation

Gorouter provides /varz and /healthz http endpoints for monitoring.

The /routes endpoint returns the entire routing table as JSON. Each route has an associated array of host:port entries.

Aside from the two monitoring http endpoints (which are only reachable via the status port), specifying the User-Agent header with a value of HTTP-Monitor/1.1 also returns the current health of the router. This is particularly useful when performing healthchecks from a Load Balancer.

Because of the nature of the data present in /varz and /routes, they require http basic authentication credentials which can be acquired through NATS. The port, user and password (pass is the config attribute) can be explicitly set in the gorouter.yml config file's status section.

status:
  port: 8080
  user: some_user
  pass: some_password

Example interaction with curl:

curl -vvv -A "HTTP-Monitor/1.1" http://127.0.0.1/
* About to connect() to 127.0.0.1 port 80 (#0)
*   Trying 127.0.0.1... connected
> GET / HTTP/1.1
> User-Agent: HTTP-Monitor/1.1
> Host: 127.0.0.1
> Accept: */*
>
< HTTP/1.1 200 OK
< Date: Mon, 10 Feb 2014 00:55:25 GMT
< Transfer-Encoding: chunked
<
ok
* Connection #0 to host 127.0.0.1 left intact
* Closing connection #0

curl -vvv "http://someuser:somepass@127.0.0.1:8080/routes"
* About to connect() to 127.0.0.1 port 8080 (#0)
*   Trying 127.0.0.1...
* connected
* Connected to 127.0.0.1 (127.0.0.1) port 8080 (#0)
* Server auth using Basic with user 'someuser'
> GET /routes HTTP/1.1
> Authorization: Basic c29tZXVzZXI6c29tZXBhc3M=
> User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8r zlib/1.2.5
> Host: 127.0.0.1:8080
> Accept: */*
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Date: Mon, 25 Mar 2013 20:31:27 GMT
< Transfer-Encoding: chunked
<
{"0295dd314aaf582f201e655cbd74ade5.cloudfoundry.me":["127.0.0.1:34567"],"03e316d6aa375d1dc1153700da5f1798.cloudfoundry.me":["127.0.0.1:34568"]}

Logs

The router's logging is specified in its YAML configuration file, in a steno configuration format. The meanings of the router's log levels are as follows:

  • fatal - An error has occurred that makes the current request unservicable. Examples: the router can't bind to its TCP port, a CF component has published invalid data to the router.
  • warn - An unexpected state has occurred. Examples: the router tried to publish data that could not be encoded as JSON
  • info, debug - An expected event has occurred. Examples: a new CF component was registered with the router, the router has begun to prune routes for stale droplets.

Contributing

Please read the contributors' guide

Documentation

The Go Gopher

There is no documentation for this package.

Directories

Path Synopsis
Godeps
_workspace/src/code.google.com/p/gogoprotobuf/proto
Package proto converts data structures to and from the wire format of protocol buffers.
Package proto converts data structures to and from the wire format of protocol buffers.
_workspace/src/github.com/apcera/nats
A Go client for the NATS messaging system (https://github.com/derekcollison/nats).
A Go client for the NATS messaging system (https://github.com/derekcollison/nats).
_workspace/src/github.com/cloudfoundry/dropsonde/autowire
Package autowire provides sensible defaults for using dropsonde.
Package autowire provides sensible defaults for using dropsonde.
_workspace/src/github.com/cloudfoundry/dropsonde/autowire/logs
Package logs provides a simple API for sending app logs from STDOUT and STDERR through the dropsonde system.
Package logs provides a simple API for sending app logs from STDOUT and STDERR through the dropsonde system.
_workspace/src/github.com/cloudfoundry/dropsonde/autowire/metrics
Package metrics provides a simple API for sending value and counter metrics through the dropsonde system.
Package metrics provides a simple API for sending value and counter metrics through the dropsonde system.
_workspace/src/github.com/cloudfoundry/dropsonde/dropsonde_marshaller
Package dropsonde_marshaller provides a tool for marshalling Envelopes to Protocol Buffer messages.
Package dropsonde_marshaller provides a tool for marshalling Envelopes to Protocol Buffer messages.
_workspace/src/github.com/cloudfoundry/dropsonde/dropsonde_unmarshaller
Package dropsonde_unmarshaller provides a tool for unmarshalling Envelopes from Protocol Buffer messages.
Package dropsonde_unmarshaller provides a tool for unmarshalling Envelopes from Protocol Buffer messages.
_workspace/src/github.com/cloudfoundry/dropsonde/events
Package events is a generated protocol buffer package.
Package events is a generated protocol buffer package.
_workspace/src/github.com/cloudfoundry/dropsonde/signature
Messages are prepended with a HMAC SHA256 signature (the signature makes up the first 32 bytes of a signed message; the remainder is the original message in cleartext).
Messages are prepended with a HMAC SHA256 signature (the signature makes up the first 32 bytes of a signed message; the remainder is the original message in cleartext).
_workspace/src/github.com/cloudfoundry/gosteno/syslog
Package syslog provides a simple interface to the system log service.
Package syslog provides a simple interface to the system log service.
_workspace/src/github.com/nu7hatch/gouuid
This package provides immutable UUID structs and the functions NewV3, NewV4, NewV5 and Parse() for generating versions 3, 4 and 5 UUIDs as specified in RFC 4122.
This package provides immutable UUID structs and the functions NewV3, NewV4, NewV5 and Parse() for generating versions 3, 4 and 5 UUIDs as specified in RFC 4122.
_workspace/src/github.com/onsi/ginkgo
Ginkgo is a BDD-style testing framework for Golang The godoc documentation describes Ginkgo's API.
Ginkgo is a BDD-style testing framework for Golang The godoc documentation describes Ginkgo's API.
_workspace/src/github.com/onsi/ginkgo/config
Ginkgo accepts a number of configuration options.
Ginkgo accepts a number of configuration options.
_workspace/src/github.com/onsi/ginkgo/ginkgo
The Ginkgo CLI The Ginkgo CLI is fully documented [here](http://onsi.github.io/ginkgo/#the_ginkgo_cli) You can also learn more by running: ginkgo help Here are some of the more commonly used commands: To install: go install github.com/onsi/ginkgo/ginkgo To run tests: ginkgo To run tests in all subdirectories: ginkgo -r To run tests in particular packages: ginkgo <flags> /path/to/package /path/to/another/package To pass arguments/flags to your tests: ginkgo <flags> <packages> -- <pass-throughs> To run tests in parallel ginkgo -p this will automatically detect the optimal number of nodes to use.
The Ginkgo CLI The Ginkgo CLI is fully documented [here](http://onsi.github.io/ginkgo/#the_ginkgo_cli) You can also learn more by running: ginkgo help Here are some of the more commonly used commands: To install: go install github.com/onsi/ginkgo/ginkgo To run tests: ginkgo To run tests in all subdirectories: ginkgo -r To run tests in particular packages: ginkgo <flags> /path/to/package /path/to/another/package To pass arguments/flags to your tests: ginkgo <flags> <packages> -- <pass-throughs> To run tests in parallel ginkgo -p this will automatically detect the optimal number of nodes to use.
_workspace/src/github.com/onsi/ginkgo/internal/remote
Aggregator is a reporter used by the Ginkgo CLI to aggregate and present parallel test output coherently as tests complete.
Aggregator is a reporter used by the Ginkgo CLI to aggregate and present parallel test output coherently as tests complete.
_workspace/src/github.com/onsi/ginkgo/reporters
Ginkgo's Default Reporter A number of command line flags are available to tweak Ginkgo's default output.
Ginkgo's Default Reporter A number of command line flags are available to tweak Ginkgo's default output.
_workspace/src/github.com/onsi/gomega
Gomega is the Ginkgo BDD-style testing framework's preferred matcher library.
Gomega is the Ginkgo BDD-style testing framework's preferred matcher library.
_workspace/src/github.com/onsi/gomega/format
Gomega's format package pretty-prints objects.
Gomega's format package pretty-prints objects.
_workspace/src/github.com/onsi/gomega/gbytes
Package gbytes provides a buffer that supports incrementally detecting input.
Package gbytes provides a buffer that supports incrementally detecting input.
_workspace/src/github.com/onsi/gomega/gexec
Package gexec provides support for testing external processes.
Package gexec provides support for testing external processes.
_workspace/src/github.com/onsi/gomega/ghttp
Package ghttp supports testing HTTP clients by providing a test server (simply a thin wrapper around httptest's server) that supports registering multiple handlers.
Package ghttp supports testing HTTP clients by providing a test server (simply a thin wrapper around httptest's server) that supports registering multiple handlers.
_workspace/src/github.com/onsi/gomega/matchers
Gomega matchers This package implements the Gomega matchers and does not typically need to be imported.
Gomega matchers This package implements the Gomega matchers and does not typically need to be imported.
_workspace/src/github.com/rcrowley/go-metrics
Go port of Coda Hale's Metrics library <https://github.com/rcrowley/go-metrics> Coda Hale's original work: <https://github.com/codahale/metrics>
Go port of Coda Hale's Metrics library <https://github.com/rcrowley/go-metrics> Coda Hale's original work: <https://github.com/codahale/metrics>
Metrics output to StatHat.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL