added sdk

Author: machinabot

README.md

@@ -1,2 +1,54 @@
-# sdk-go
-Official Go SDK for Machine Box
+# Machine Box Go SDK
+
+The official Machine Box Go SDK provides Go clients for each box.
+
+## Usage
+
+Go get the repo:
+
+```
+go get github.com/machinebox/mb/exp/sdk-go
+```
+
+Then import the package of the box you wish to use:
+
+```go
+import "github.com/machinebox/mb/exp/sdk-go/facebox"
+```
+
+Then create a client, providing the address of the running box.
+
+(To get a box running locally, see the instructions at https://machinebox.io/account)
+
+```go
+faceboxClient := facebox.New("http://localhost:8080")
+```
+
+It is recommended that you consider the startup time a box needs before it
+is ready. The simplest approach is to use the boxutil.WaitForReady function:
+
+```go
+err := boxutil.WaitForReady(ctx, faceboxClient)
+if err != nil {
+    log.Fatalln("error waiting for box:", err)
+}
+```
+
+A more advanced solution is to get notified whenever the status of a box changes
+using the boxutil.StatusChan feature:
+
+```go
+go func(){
+    statusChan := boxutil.StatusChan(ctx, faceboxClient)
+    for {
+        select {
+        case status := <-statusChan:
+            if !boxutil.IsReady(status) {
+                log.Println("TODO: Pause work, the box isn't ready")
+            } else {
+                log.Println("TODO: resume work, the box is ready to go")
+            }
+        }
+    }
+}()
+```

boxutil/info.go

@@ -0,0 +1,15 @@
+package boxutil
+
+// Box represents a box client capable of returning
+// Info.
+type Box interface {
+	Info() (*Info, error)
+}
+
+// Info describes box information.
+type Info struct {
+	Name    string
+	Version int
+	Build   string
+	Status  string
+}

boxutil/status.go

@@ -0,0 +1,66 @@
+package boxutil
+
+import (
+	"context"
+	"errors"
+	"time"
+)
+
+// ErrCanceled is returned when the context cancels or times out
+// an operation.
+var ErrCanceled = errors.New("context is done")
+
+// readyCheckInterval is the interval to wait between checking
+// the status in StatusChan.
+// Unexported because 1 second is sensible, but configurable to make
+// tests run quicker.
+var readyCheckInterval = 1 * time.Second
+
+// StatusChan gets a channel that periodically gets the box info
+// and sends a message whenever the status changes.
+func StatusChan(ctx context.Context, i Box) <-chan string {
+	statusChan := make(chan string)
+	go func() {
+		var lastStatus string
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			default:
+				time.Sleep(readyCheckInterval)
+				status := "unavailable"
+				info, err := i.Info()
+				if err == nil {
+					status = info.Status
+				}
+				if status != lastStatus {
+					lastStatus = status
+					statusChan <- status
+				}
+			}
+		}
+	}()
+	return statusChan
+}
+
+// WaitForReady blocks until the Box is ready.
+func WaitForReady(ctx context.Context, i Box) error {
+	ctx, cancel := context.WithCancel(ctx)
+	defer cancel()
+	statusChan := StatusChan(ctx, i)
+	for {
+		select {
+		case <-ctx.Done():
+			return ErrCanceled
+		case status := <-statusChan:
+			if IsReady(status) {
+				return nil
+			}
+		}
+	}
+}
+
+// IsReady gets whether the box info status is ready or not.
+func IsReady(status string) bool {
+	return status == "ready"
+}

boxutil/status_test.go

@@ -0,0 +1,96 @@
+package boxutil
+
+import (
+	"context"
+	"errors"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/matryer/is"
+)
+
+func init() {
+	// quicker for testing
+	readyCheckInterval = 100 * time.Millisecond
+}
+
+func TestStatusChan(t *testing.T) {
+	is := is.New(t)
+
+	i := &testBox{}
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	status := StatusChan(ctx, i)
+	is.Equal(<-status, "starting...")
+	i.setReady()
+	is.Equal(<-status, "ready")
+	i.setError()
+	is.Equal(<-status, "unavailable")
+	i.clearError()
+	is.Equal(<-status, "ready")
+
+}
+
+func TestWaitForReady(t *testing.T) {
+	is := is.New(t)
+	i := &testBox{}
+	ctx, cancel := context.WithCancel(context.Background())
+	time.AfterFunc(300*time.Millisecond, cancel)
+	go func() {
+		time.Sleep(200 * time.Millisecond)
+		i.setReady()
+	}()
+	err := WaitForReady(ctx, i)
+	is.NoErr(err)
+}
+
+func TestWaitForReadyTimeout(t *testing.T) {
+	is := is.New(t)
+	i := &testBox{}
+	ctx, cancel := context.WithCancel(context.Background())
+	time.AfterFunc(100*time.Millisecond, cancel)
+	go func() {
+		time.Sleep(200 * time.Millisecond)
+		i.setReady()
+	}()
+	err := WaitForReady(ctx, i)
+	is.Equal(err, ErrCanceled)
+}
+
+type testBox struct {
+	lock  sync.Mutex
+	ready bool
+	err   error
+}
+
+func (i *testBox) setReady() {
+	i.lock.Lock()
+	defer i.lock.Unlock()
+	i.ready = true
+}
+
+func (i *testBox) setError() {
+	i.lock.Lock()
+	defer i.lock.Unlock()
+	i.err = errors.New("cannot reach server")
+}
+
+func (i *testBox) clearError() {
+	i.lock.Lock()
+	defer i.lock.Unlock()
+	i.err = nil
+}
+
+func (i *testBox) Info() (*Info, error) {
+	i.lock.Lock()
+	defer i.lock.Unlock()
+	if i.err != nil {
+		return nil, i.err
+	}
+	if i.ready {
+		return &Info{Status: "ready"}, nil
+	}
+	return &Info{Status: "starting..."}, nil
+}

facebox/facebox.go

@@ -0,0 +1,82 @@
+// Package facebox provides a client for accessing facebox services.
+package facebox
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/url"
+	"time"
+
+	"github.com/machinebox/mb/exp/sdk-go/boxutil"
+)
+
+// Face represents a face in an image.
+type Face struct {
+	Rect    Rect
+	ID      string
+	Name    string
+	Matched bool
+}
+
+// Rect represents the coordinates of a face within an image.
+type Rect struct {
+	Top, Left     int
+	Width, Height int
+}
+
+// Similar represents a similar face.
+type Similar struct {
+	ID   string
+	Name string
+}
+
+// Client is an HTTP client that can make requests to the box.
+type Client struct {
+	addr string
+
+	// HTTPClient is the http.Client that will be used to
+	// make requests.
+	HTTPClient *http.Client
+}
+
+// make sure the Client implements boxutil.Box
+var _ boxutil.Box = (*Client)(nil)
+
+// New creates a new Client.
+func New(addr string) *Client {
+	return &Client{
+		addr: addr,
+		HTTPClient: &http.Client{
+			Timeout: 10 * time.Second,
+		},
+	}
+}
+
+// Info gets the details about the box.
+func (c *Client) Info() (*boxutil.Info, error) {
+	var info boxutil.Info
+	u, err := url.Parse(c.addr + "/info")
+	if err != nil {
+		return nil, err
+	}
+	if !u.IsAbs() {
+		return nil, errors.New("box address must be absolute")
+	}
+	resp, err := c.HTTPClient.Get(u.String())
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	if err := json.NewDecoder(resp.Body).Decode(&info); err != nil {
+		return nil, err
+	}
+	return &info, nil
+}
+
+// ErrFacebox represents an error from nudebox.
+type ErrFacebox string
+
+func (e ErrFacebox) Error() string {
+	return "facebox: " + string(e)
+}

facebox/facebox_check.go

@@ -0,0 +1,78 @@
+package facebox
+
+import (
+	"bytes"
+	"encoding/json"
+	"io"
+	"mime/multipart"
+	"net/url"
+
+	"github.com/pkg/errors"
+)
+
+// Check checks the image in the io.Reader for faces.
+func (c *Client) Check(image io.Reader) ([]Face, error) {
+	var buf bytes.Buffer
+	w := multipart.NewWriter(&buf)
+	fw, err := w.CreateFormFile("file", "image.dat")
+	if err != nil {
+		return nil, err
+	}
+	_, err = io.Copy(fw, image)
+	if err != nil {
+		return nil, err
+	}
+	if err = w.Close(); err != nil {
+		return nil, err
+	}
+	u, err := url.Parse(c.addr + "/facebox/check")
+	if err != nil {
+		return nil, err
+	}
+	if !u.IsAbs() {
+		return nil, errors.New("box address must be absolute")
+	}
+	resp, err := c.HTTPClient.Post(u.String(), w.FormDataContentType(), &buf)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	return c.parseCheckResponse(resp.Body)
+}
+
+// CheckURL checks the image at the specified URL for faces.
+func (c *Client) CheckURL(imageURL *url.URL) ([]Face, error) {
+	u, err := url.Parse(c.addr + "/facebox/check")
+	if err != nil {
+		return nil, err
+	}
+	if !u.IsAbs() {
+		return nil, errors.New("box address must be absolute")
+	}
+	if !imageURL.IsAbs() {
+		return nil, errors.New("url must be absolute")
+	}
+	form := url.Values{}
+	form.Set("url", imageURL.String())
+	resp, err := c.HTTPClient.PostForm(u.String(), form)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	return c.parseCheckResponse(resp.Body)
+}
+
+func (c *Client) parseCheckResponse(r io.Reader) ([]Face, error) {
+	var checkResponse struct {
+		Success bool
+		Error   string
+		Faces   []Face
+	}
+	if err := json.NewDecoder(r).Decode(&checkResponse); err != nil {
+		return nil, errors.Wrap(err, "decoding response")
+	}
+	if !checkResponse.Success {
+		return nil, ErrFacebox(checkResponse.Error)
+	}
+	return checkResponse.Faces, nil
+}