Client readme

CHANGELOG.md

@@ -7,6 +7,7 @@
 - [#1877](https://github.com/influxdb/influxdb/pull/1877): Broker clients track broker leader
 - [#1862](https://github.com/influxdb/influxdb/pull/1862): Fix memory leak in `httpd.serveWait`. Thanks @mountkin
 - [#1868](https://github.com/influxdb/influxdb/pull/1868): Use `BatchPoints` for `client.Write` method. Thanks @vladlopes, @georgmu, @d2g, @evanphx, @akolosov.
+- [#1881](https://github.com/influxdb/influxdb/pull/1881): Update documentation for `client` package.  Misc library tweaks.
 
 ## v0.9.0-rc9 [2015-03-06]
 

client/README.md

@@ -1,4 +1,180 @@
 InfluxDB Go Client Library
 ============
 
-# TODO Add links to the godoc and examples when they are written
+# package client
+
+```go
+import "github.com/influxdb/influxdb/client"
+ ```
+
+
+#FUNCTIONS
+
+```go
+func EpochToTime(epoch int64, precision string) (time.Time, error)
+```
+EpochToTime takes a unix epoch time and uses precision to return back a
+time.Time
+
+```go
+func SetPrecision(t time.Time, precision string) time.Time
+```
+SetPrecision will round a time to the specified precision
+
+#TYPES
+
+```go
+type BatchPoints struct {
+    Points          []Point           `json:"points,omitempty"`
+    Database        string            `json:"database,omitempty"`
+    RetentionPolicy string            `json:"retentionPolicy,omitempty"`
+    Tags            map[string]string `json:"tags,omitempty"`
+    Timestamp       time.Time         `json:"timestamp,omitempty"`
+    Precision       string            `json:"precision,omitempty"`
+}
+```
+BatchPoints is used to send batched data in a single write. Database and
+Points are required If no retention policy is specified, it will use the
+databases default retention policy. If tags are specified, they will be
+"merged" with all points. If a point already has that tag, it is
+ignored. If timestamp is specified, it will be applied to any point with
+an empty timestamp. Precision can be specified if the timestamp is in
+epoch format (integer). Valid values for Precision are n, u, ms, s, m,
+and h
+
+```go
+func (bp *BatchPoints) UnmarshalJSON(b []byte) error
+```
+UnmarshalJSON decodes the data into the BatchPoints struct
+
+```go
+type Client struct {
+    // contains filtered or unexported fields
+}
+```
+Client is used to make calls to the server.
+
+```go
+func NewClient(c Config) (*Client, error)
+```
+NewClient will instantiate and return a connected client to issue
+commands to the server.
+
+```go
+func (c *Client) Addr() string
+```
+Addr provides the current url as a string of the server the client is
+connected to.
+
+```go
+func (c *Client) Ping() (time.Duration, string, error)
+```
+Ping will check to see if the server is up Ping returns how long the
+requeset took, the version of the server it connected to, and an error
+if one occured.
+
+```go
+func (c *Client) Query(q Query) (*Results, error)
+```
+Query sends a command to the server and returns the Results
+
+```go
+func (c *Client) Write(bp BatchPoints) (*Results, error)
+```
+Write takes BatchPoints and allows for writing of multiple points with
+defaults If successful, error is nil and Results is nil If an error
+occurs, Results may contain additional information if populated.
+
+```go
+type Config struct {
+    URL       url.URL
+    Username  string
+    Password  string
+    UserAgent string
+}
+```
+Config is used to specify what server to connect to. URL: The URL of the
+server connecting to. Username/Password are optional. They will be
+passed via basic auth if provided. UserAgent: If not provided, will
+default "InfluxDBClient/" + version,
+
+```go
+type Point struct {
+    Name      string
+    Tags      map[string]string
+    Timestamp time.Time
+    Fields    map[string]interface{}
+    Precision string
+}
+```
+Point defines the fields that will be written to the database Name,
+Timestamp, and Fields are required Precision can be specified if the
+timestamp is in epoch format (integer). Valid values for Precision are
+n, u, ms, s, m, and h
+
+```go
+func (p *Point) MarshalJSON() ([]byte, error)
+```
+MarshalJSON will format the time in RFC3339Nano Precision is also
+ignored as it is only used for writing, not reading Or another way to
+say it is we always send back in nanosecond precision
+
+```go
+func (p *Point) UnmarshalJSON(b []byte) error
+```
+UnmarshalJSON decodes the data into the Point struct
+
+```go
+type Query struct {
+    Command  string
+    Database string
+}
+```
+Query is used to send a command to the server. Both Command and Database
+are required.
+
+```go
+type Result struct {
+    Series []influxql.Row
+    Err    error
+}
+```
+Result represents a resultset returned from a single statement.
+
+```go
+func (r *Result) MarshalJSON() ([]byte, error)
+```
+MarshalJSON encodes the result into JSON.
+
+```go
+func (r *Result) UnmarshalJSON(b []byte) error
+```
+UnmarshalJSON decodes the data into the Result struct
+
+```go
+type Results struct {
+    Results []Result
+    Err     error
+}
+```
+Results represents a list of statement results.
+
+```go
+func (a Results) Error() error
+```
+Error returns the first error from any statement. Returns nil if no
+errors occurred on any statements.
+
+```go
+func (r *Results) MarshalJSON() ([]byte, error)
+```
+MarshalJSON encodes the result into JSON.
+
+```go
+func (r *Results) UnmarshalJSON(b []byte) error
+```
+UnmarshalJSON decodes the data into the Results struct
+
+# Examples
+
+You can see a use of the client libray in the [InfluxDB CLI](https://github.com/influxdb/influxdb/blob/master/cmd/influx/main.go).

client/influxdb.go

@@ -12,18 +12,24 @@ import (
 	"github.com/influxdb/influxdb/influxql"
 )
 
+// Query is used to send a command to the server. Both Command and Database are required.
 type Query struct {
 	Command  string
 	Database string
 }
 
+// Config is used to specify what server to connect to.
+// URL: The URL of the server connecting to.
+// Username/Password are optional.  They will be passed via basic auth if provided.
+// UserAgent: If not provided, will default "InfluxDBClient",
 type Config struct {
 	URL       url.URL
 	Username  string
 	Password  string
 	UserAgent string
 }
 
+// Client is used to make calls to the server.
 type Client struct {
 	url        url.URL
 	username   string
@@ -32,6 +38,7 @@ type Client struct {
 	userAgent  string
 }
 
+// NewClient will instantiate and return a connected client to issue commands to the server.
 func NewClient(c Config) (*Client, error) {
 	client := Client{
 		url:        c.URL,
@@ -40,13 +47,20 @@ func NewClient(c Config) (*Client, error) {
 		httpClient: &http.Client{},
 		userAgent:  c.UserAgent,
 	}
+	if client.userAgent == "" {
+		client.userAgent = "InfluxDBClient"
+	}
 	return &client, nil
 }
 
+// Query sends a command to the server and returns the Results
 func (c *Client) Query(q Query) (*Results, error) {
 	u := c.url
 
 	u.Path = "query"
+	if c.username != "" {
+		u.User = url.UserPassword(c.username, c.password)
+	}
 	values := u.Query()
 	values.Set("q", q.Command)
 	values.Set("db", q.Database)
@@ -56,9 +70,7 @@ func (c *Client) Query(q Query) (*Results, error) {
 	if err != nil {
 		return nil, err
 	}
-	if c.userAgent != "" {
-		req.Header.Set("User-Agent", c.userAgent)
-	}
+	req.Header.Set("User-Agent", c.userAgent)
 	resp, err := c.httpClient.Do(req)
 	if err != nil {
 		return nil, err
@@ -75,6 +87,9 @@ func (c *Client) Query(q Query) (*Results, error) {
 	return &results, nil
 }
 
+// Write takes BatchPoints and allows for writing of multiple points with defaults
+// If successful, error is nil and Results is nil
+// If an error occurs, Results may contain additional information if populated.
 func (c *Client) Write(bp BatchPoints) (*Results, error) {
 	c.url.Path = "write"
 
@@ -88,9 +103,7 @@ func (c *Client) Write(bp BatchPoints) (*Results, error) {
 		return nil, err
 	}
 	req.Header.Set("Content-Type", "application/json")
-	if c.userAgent != "" {
-		req.Header.Set("User-Agent", c.userAgent)
-	}
+	req.Header.Set("User-Agent", c.userAgent)
 	resp, err := c.httpClient.Do(req)
 	if err != nil {
 		return nil, err
@@ -109,9 +122,11 @@ func (c *Client) Write(bp BatchPoints) (*Results, error) {
 		return &results, results.Error()
 	}
 
-	return &results, nil
+	return nil, nil
 }
 
+// Ping will check to see if the server is up
+// Ping returns how long the requeset took, the version of the server it connected to, and an error if one occured.
 func (c *Client) Ping() (time.Duration, string, error) {
 	now := time.Now()
 	u := c.url
@@ -121,9 +136,7 @@ func (c *Client) Ping() (time.Duration, string, error) {
 	if err != nil {
 		return 0, "", err
 	}
-	if c.userAgent != "" {
-		req.Header.Set("User-Agent", c.userAgent)
-	}
+	req.Header.Set("User-Agent", c.userAgent)
 	resp, err := c.httpClient.Do(req)
 	if err != nil {
 		return 0, "", err
@@ -183,7 +196,8 @@ type Results struct {
 	Err     error
 }
 
-func (r Results) MarshalJSON() ([]byte, error) {
+// MarshalJSON encodes the result into JSON.
+func (r *Results) MarshalJSON() ([]byte, error) {
 	// Define a struct that outputs "error" as a string.
 	var o struct {
 		Results []Result `json:"results,omitempty"`
@@ -234,6 +248,9 @@ func (a Results) Error() error {
 }
 
 // Point defines the fields that will be written to the database
+// Name, Timestamp, and Fields are required
+// Precision can be specified if the timestamp is in epoch format (integer).
+// Valid values for Precision are n, u, ms, s, m, and h
 type Point struct {
 	Name      string
 	Tags      map[string]string
@@ -341,6 +358,12 @@ func normalizeFields(fields map[string]interface{}) map[string]interface{} {
 }
 
 // BatchPoints is used to send batched data in a single write.
+// Database and Points are required
+// If no retention policy is specified, it will use the databases default retention policy.
+// If tags are specified, they will be "merged" with all points.  If a point already has that tag, it is ignored.
+// If timestamp is specified, it will be applied to any point with an empty timestamp.
+// Precision can be specified if the timestamp is in epoch format (integer).
+// Valid values for Precision are n, u, ms, s, m, and h
 type BatchPoints struct {
 	Points          []Point           `json:"points,omitempty"`
 	Database        string            `json:"database,omitempty"`
@@ -409,6 +432,7 @@ func (bp *BatchPoints) UnmarshalJSON(b []byte) error {
 
 // utility functions
 
+// Addr provides the current url as a string of the server the client is connected to.
 func (c *Client) Addr() string {
 	return c.url.String()
 }

client/influxdb_test.go

@@ -6,6 +6,7 @@ import (
 	"net/http"
 	"net/http/httptest"
 	"net/url"
+	"strings"
 	"testing"
 	"time"
 
@@ -134,8 +135,6 @@ func TestClient_UserAgent(t *testing.T) {
 		t.Fatalf("unexpected error.  expected %v, actual %v", nil, err)
 	}
 
-	defaultUserAgent := receivedUserAgent
-
 	tests := []struct {
 		name      string
 		userAgent string
@@ -144,7 +143,7 @@ func TestClient_UserAgent(t *testing.T) {
 		{
 			name:      "Empty user agent",
 			userAgent: "",
-			expected:  defaultUserAgent,
+			expected:  "InfluxDBClient",
 		},
 		{
 			name:      "Custom user agent",
@@ -167,7 +166,7 @@ func TestClient_UserAgent(t *testing.T) {
 		if err != nil {
 			t.Fatalf("unexpected error.  expected %v, actual %v", nil, err)
 		}
-		if receivedUserAgent != test.expected {
+		if !strings.HasPrefix(receivedUserAgent, test.expected) {
 			t.Fatalf("Unexpected user agent. expected %v, actual %v", test.expected, receivedUserAgent)
 		}
 
@@ -177,7 +176,7 @@ func TestClient_UserAgent(t *testing.T) {
 		if err != nil {
 			t.Fatalf("unexpected error.  expected %v, actual %v", nil, err)
 		}
-		if receivedUserAgent != test.expected {
+		if !strings.HasPrefix(receivedUserAgent, test.expected) {
 			t.Fatalf("Unexpected user agent. expected %v, actual %v", test.expected, receivedUserAgent)
 		}