Consul prepared queries

CHANGELOG.md

@@ -26,6 +26,10 @@ FEATURES:
 * Consul now builds under Go 1.5.1 by default [GH-1345]
 * Added built-in support for running health checks inside Docker containers
   [GH-1343]
+* Added prepared queries which support service health queries with rich
+  features such as filters for multiple tags and failover to remote datacenters
+  based on network coordinates; these are available via HTTP as well as the
+  DNS interface [GH-1389]
 
 BUG FIXES:
 

acl/acl.go

@@ -70,6 +70,12 @@ type ACL interface {
 
 	// ACLModify checks for permission to manipulate ACLs
 	ACLModify() bool
+
+	// QueryList checks for permission to list all the prepared queries.
+	QueryList() bool
+
+	// QueryModify checks for permission to modify any prepared query.
+	QueryModify() bool
 }
 
 // StaticACL is used to implement a base ACL policy. It either
@@ -124,6 +130,14 @@ func (s *StaticACL) ACLModify() bool {
 	return s.allowManage
 }
 
+func (s *StaticACL) QueryList() bool {
+	return s.allowManage
+}
+
+func (s *StaticACL) QueryModify() bool {
+	return s.allowManage
+}
+
 // AllowAll returns an ACL rule that allows all operations
 func AllowAll() ACL {
 	return allowAll
@@ -374,3 +388,13 @@ func (p *PolicyACL) ACLList() bool {
 func (p *PolicyACL) ACLModify() bool {
 	return p.parent.ACLModify()
 }
+
+// QueryList checks if listing of all prepared queries is allowed.
+func (p *PolicyACL) QueryList() bool {
+	return p.parent.QueryList()
+}
+
+// QueryModify checks if modifying of any prepared query is allowed.
+func (p *PolicyACL) QueryModify() bool {
+	return p.parent.QueryModify()
+}

acl/acl_test.go

@@ -65,6 +65,12 @@ func TestStaticACL(t *testing.T) {
 	if all.ACLModify() {
 		t.Fatalf("should not allow")
 	}
+	if all.QueryList() {
+		t.Fatalf("should not allow")
+	}
+	if all.QueryModify() {
+		t.Fatalf("should not allow")
+	}
 
 	if none.KeyRead("foobar") {
 		t.Fatalf("should not allow")
@@ -102,6 +108,12 @@ func TestStaticACL(t *testing.T) {
 	if none.ACLModify() {
 		t.Fatalf("should not allow")
 	}
+	if none.QueryList() {
+		t.Fatalf("should not allow")
+	}
+	if none.QueryModify() {
+		t.Fatalf("should not allow")
+	}
 
 	if !manage.KeyRead("foobar") {
 		t.Fatalf("should allow")
@@ -133,6 +145,12 @@ func TestStaticACL(t *testing.T) {
 	if !manage.ACLModify() {
 		t.Fatalf("should allow")
 	}
+	if !manage.QueryList() {
+		t.Fatalf("should allow")
+	}
+	if !manage.QueryModify() {
+		t.Fatalf("should allow")
+	}
 }
 
 func TestPolicyACL(t *testing.T) {
@@ -369,6 +387,20 @@ func TestPolicyACL_Parent(t *testing.T) {
 			t.Fatalf("Write fail: %#v", c)
 		}
 	}
+
+	// Check some management functions that chain up
+	if acl.ACLList() {
+		t.Fatalf("should not allow")
+	}
+	if acl.ACLModify() {
+		t.Fatalf("should not allow")
+	}
+	if acl.QueryList() {
+		t.Fatalf("should not allow")
+	}
+	if acl.QueryModify() {
+		t.Fatalf("should not allow")
+	}
 }
 
 func TestPolicyACL_Keyring(t *testing.T) {

api/prepared_query.go

@@ -0,0 +1,173 @@
+package api
+
+// QueryDatacenterOptions sets options about how we fail over if there are no
+// healthy nodes in the local datacenter.
+type QueryDatacenterOptions struct {
+	// NearestN is set to the number of remote datacenters to try, based on
+	// network coordinates.
+	NearestN int
+
+	// Datacenters is a fixed list of datacenters to try after NearestN. We
+	// never try a datacenter multiple times, so those are subtracted from
+	// this list before proceeding.
+	Datacenters []string
+}
+
+// QueryDNSOptions controls settings when query results are served over DNS.
+type QueryDNSOptions struct {
+	// TTL is the time to live for the served DNS results.
+	TTL string
+}
+
+// ServiceQuery is used to query for a set of healthy nodes offering a specific
+// service.
+type ServiceQuery struct {
+	// Service is the service to query.
+	Service string
+
+	// Failover controls what we do if there are no healthy nodes in the
+	// local datacenter.
+	Failover QueryDatacenterOptions
+
+	// If OnlyPassing is true then we will only include nodes with passing
+	// health checks (critical AND warning checks will cause a node to be
+	// discarded)
+	OnlyPassing bool
+
+	// Tags are a set of required and/or disallowed tags. If a tag is in
+	// this list it must be present. If the tag is preceded with "!" then
+	// it is disallowed.
+	Tags []string
+}
+
+// PrepatedQueryDefinition defines a complete prepared query.
+type PreparedQueryDefinition struct {
+	// ID is this UUID-based ID for the query, always generated by Consul.
+	ID string
+
+	// Name is an optional friendly name for the query supplied by the
+	// user. NOTE - if this feature is used then it will reduce the security
+	// of any read ACL associated with this query/service since this name
+	// can be used to locate nodes with supplying any ACL.
+	Name string
+
+	// Session is an optional session to tie this query's lifetime to. If
+	// this is omitted then the query will not expire.
+	Session string
+
+	// Token is the ACL token used when the query was created, and it is
+	// used when a query is subsequently executed. This token, or a token
+	// with management privileges, must be used to change the query later.
+	Token string
+
+	// Service defines a service query (leaving things open for other types
+	// later).
+	Service ServiceQuery
+
+	// DNS has options that control how the results of this query are
+	// served over DNS.
+	DNS QueryDNSOptions
+}
+
+// PreparedQueryExecuteResponse has the results of executing a query.
+type PreparedQueryExecuteResponse struct {
+	// Service is the service that was queried.
+	Service string
+
+	// Nodes has the nodes that were output by the query.
+	Nodes []ServiceEntry
+
+	// DNS has the options for serving these results over DNS.
+	DNS QueryDNSOptions
+
+	// Datacenter is the datacenter that these results came from.
+	Datacenter string
+
+	// Failovers is a count of how many times we had to query a remote
+	// datacenter.
+	Failovers int
+}
+
+// PreparedQuery can be used to query the prepared query endpoints.
+type PreparedQuery struct {
+	c *Client
+}
+
+// PreparedQuery returns a handle to the prepared query endpoints.
+func (c *Client) PreparedQuery() *PreparedQuery {
+	return &PreparedQuery{c}
+}
+
+// Create makes a new prepared query. The ID of the new query is returned.
+func (c *PreparedQuery) Create(query *PreparedQueryDefinition, q *WriteOptions) (string, *WriteMeta, error) {
+	r := c.c.newRequest("POST", "/v1/query")
+	r.setWriteOptions(q)
+	r.obj = query
+	rtt, resp, err := requireOK(c.c.doRequest(r))
+	if err != nil {
+		return "", nil, err
+	}
+	defer resp.Body.Close()
+
+	wm := &WriteMeta{}
+	wm.RequestTime = rtt
+
+	var out struct{ ID string }
+	if err := decodeBody(resp, &out); err != nil {
+		return "", nil, err
+	}
+	return out.ID, wm, nil
+}
+
+// Update makes updates to an existing prepared query.
+func (c *PreparedQuery) Update(query *PreparedQueryDefinition, q *WriteOptions) (*WriteMeta, error) {
+	return c.c.write("/v1/query/"+query.ID, query, nil, q)
+}
+
+// List is used to fetch all the prepared queries (always requires a management
+// token).
+func (c *PreparedQuery) List(q *QueryOptions) ([]*PreparedQueryDefinition, *QueryMeta, error) {
+	var out []*PreparedQueryDefinition
+	qm, err := c.c.query("/v1/query", &out, q)
+	if err != nil {
+		return nil, nil, err
+	}
+	return out, qm, nil
+}
+
+// Get is used to fetch a specific prepared query.
+func (c *PreparedQuery) Get(queryID string, q *QueryOptions) ([]*PreparedQueryDefinition, *QueryMeta, error) {
+	var out []*PreparedQueryDefinition
+	qm, err := c.c.query("/v1/query/"+queryID, &out, q)
+	if err != nil {
+		return nil, nil, err
+	}
+	return out, qm, nil
+}
+
+// Delete is used to delete a specific prepared query.
+func (c *PreparedQuery) Delete(queryID string, q *QueryOptions) (*QueryMeta, error) {
+	r := c.c.newRequest("DELETE", "/v1/query/"+queryID)
+	r.setQueryOptions(q)
+	rtt, resp, err := requireOK(c.c.doRequest(r))
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	qm := &QueryMeta{}
+	parseQueryMeta(resp, qm)
+	qm.RequestTime = rtt
+	return qm, nil
+}
+
+// Execute is used to execute a specific prepared query. You can execute using
+// a query ID or name.
+func (c *PreparedQuery) Execute(queryIDOrName string, q *QueryOptions) (*PreparedQueryExecuteResponse, *QueryMeta, error) {
+	var out *PreparedQueryExecuteResponse
+	qm, err := c.c.query("/v1/query/"+queryIDOrName+"/execute", &out, q)
+	if err != nil {
+		return nil, nil, err
+	}
+	return out, qm, nil
+}