1package api 2 3// QueryDatacenterOptions sets options about how we fail over if there are no 4// healthy nodes in the local datacenter. 5type QueryDatacenterOptions struct { 6 // NearestN is set to the number of remote datacenters to try, based on 7 // network coordinates. 8 NearestN int 9 10 // Datacenters is a fixed list of datacenters to try after NearestN. We 11 // never try a datacenter multiple times, so those are subtracted from 12 // this list before proceeding. 13 Datacenters []string 14} 15 16// QueryDNSOptions controls settings when query results are served over DNS. 17type QueryDNSOptions struct { 18 // TTL is the time to live for the served DNS results. 19 TTL string 20} 21 22// ServiceQuery is used to query for a set of healthy nodes offering a specific 23// service. 24type ServiceQuery struct { 25 // Service is the service to query. 26 Service string 27 28 // Near allows baking in the name of a node to automatically distance- 29 // sort from. The magic "_agent" value is supported, which sorts near 30 // the agent which initiated the request by default. 31 Near string 32 33 // Failover controls what we do if there are no healthy nodes in the 34 // local datacenter. 35 Failover QueryDatacenterOptions 36 37 // If OnlyPassing is true then we will only include nodes with passing 38 // health checks (critical AND warning checks will cause a node to be 39 // discarded) 40 OnlyPassing bool 41 42 // Tags are a set of required and/or disallowed tags. If a tag is in 43 // this list it must be present. If the tag is preceded with "!" then 44 // it is disallowed. 45 Tags []string 46} 47 48// QueryTemplate carries the arguments for creating a templated query. 49type QueryTemplate struct { 50 // Type specifies the type of the query template. Currently only 51 // "name_prefix_match" is supported. This field is required. 52 Type string 53 54 // Regexp allows specifying a regex pattern to match against the name 55 // of the query being executed. 56 Regexp string 57} 58 59// PrepatedQueryDefinition defines a complete prepared query. 60type PreparedQueryDefinition struct { 61 // ID is this UUID-based ID for the query, always generated by Consul. 62 ID string 63 64 // Name is an optional friendly name for the query supplied by the 65 // user. NOTE - if this feature is used then it will reduce the security 66 // of any read ACL associated with this query/service since this name 67 // can be used to locate nodes with supplying any ACL. 68 Name string 69 70 // Session is an optional session to tie this query's lifetime to. If 71 // this is omitted then the query will not expire. 72 Session string 73 74 // Token is the ACL token used when the query was created, and it is 75 // used when a query is subsequently executed. This token, or a token 76 // with management privileges, must be used to change the query later. 77 Token string 78 79 // Service defines a service query (leaving things open for other types 80 // later). 81 Service ServiceQuery 82 83 // DNS has options that control how the results of this query are 84 // served over DNS. 85 DNS QueryDNSOptions 86 87 // Template is used to pass through the arguments for creating a 88 // prepared query with an attached template. If a template is given, 89 // interpolations are possible in other struct fields. 90 Template QueryTemplate 91} 92 93// PreparedQueryExecuteResponse has the results of executing a query. 94type PreparedQueryExecuteResponse struct { 95 // Service is the service that was queried. 96 Service string 97 98 // Nodes has the nodes that were output by the query. 99 Nodes []ServiceEntry 100 101 // DNS has the options for serving these results over DNS. 102 DNS QueryDNSOptions 103 104 // Datacenter is the datacenter that these results came from. 105 Datacenter string 106 107 // Failovers is a count of how many times we had to query a remote 108 // datacenter. 109 Failovers int 110} 111 112// PreparedQuery can be used to query the prepared query endpoints. 113type PreparedQuery struct { 114 c *Client 115} 116 117// PreparedQuery returns a handle to the prepared query endpoints. 118func (c *Client) PreparedQuery() *PreparedQuery { 119 return &PreparedQuery{c} 120} 121 122// Create makes a new prepared query. The ID of the new query is returned. 123func (c *PreparedQuery) Create(query *PreparedQueryDefinition, q *WriteOptions) (string, *WriteMeta, error) { 124 r := c.c.newRequest("POST", "/v1/query") 125 r.setWriteOptions(q) 126 r.obj = query 127 rtt, resp, err := requireOK(c.c.doRequest(r)) 128 if err != nil { 129 return "", nil, err 130 } 131 defer resp.Body.Close() 132 133 wm := &WriteMeta{} 134 wm.RequestTime = rtt 135 136 var out struct{ ID string } 137 if err := decodeBody(resp, &out); err != nil { 138 return "", nil, err 139 } 140 return out.ID, wm, nil 141} 142 143// Update makes updates to an existing prepared query. 144func (c *PreparedQuery) Update(query *PreparedQueryDefinition, q *WriteOptions) (*WriteMeta, error) { 145 return c.c.write("/v1/query/"+query.ID, query, nil, q) 146} 147 148// List is used to fetch all the prepared queries (always requires a management 149// token). 150func (c *PreparedQuery) List(q *QueryOptions) ([]*PreparedQueryDefinition, *QueryMeta, error) { 151 var out []*PreparedQueryDefinition 152 qm, err := c.c.query("/v1/query", &out, q) 153 if err != nil { 154 return nil, nil, err 155 } 156 return out, qm, nil 157} 158 159// Get is used to fetch a specific prepared query. 160func (c *PreparedQuery) Get(queryID string, q *QueryOptions) ([]*PreparedQueryDefinition, *QueryMeta, error) { 161 var out []*PreparedQueryDefinition 162 qm, err := c.c.query("/v1/query/"+queryID, &out, q) 163 if err != nil { 164 return nil, nil, err 165 } 166 return out, qm, nil 167} 168 169// Delete is used to delete a specific prepared query. 170func (c *PreparedQuery) Delete(queryID string, q *WriteOptions) (*WriteMeta, error) { 171 r := c.c.newRequest("DELETE", "/v1/query/"+queryID) 172 r.setWriteOptions(q) 173 rtt, resp, err := requireOK(c.c.doRequest(r)) 174 if err != nil { 175 return nil, err 176 } 177 defer resp.Body.Close() 178 179 wm := &WriteMeta{} 180 wm.RequestTime = rtt 181 return wm, nil 182} 183 184// Execute is used to execute a specific prepared query. You can execute using 185// a query ID or name. 186func (c *PreparedQuery) Execute(queryIDOrName string, q *QueryOptions) (*PreparedQueryExecuteResponse, *QueryMeta, error) { 187 var out *PreparedQueryExecuteResponse 188 qm, err := c.c.query("/v1/query/"+queryIDOrName+"/execute", &out, q) 189 if err != nil { 190 return nil, nil, err 191 } 192 return out, qm, nil 193} 194