Initial Commit

Author: nerdyc

README.md

@@ -0,0 +1,29 @@
+# An Easily Tested, SQL-backed JSON Web Service in Go.
+
+This repo demonstrates how to write an easily-tested JSON web service in
+Go, with a PostgreSQL database. [It's a companion to a blog post I wrote](http://nerdyc.com/blog/2016/06/16/testing-web-apps-end-to-end-in-go/).
+
+Tests in this project run against a local PostgreSQL server, and make
+real HTTP calls to ensure that it works from end-to-end.
+
+## Overview
+
+Here's the gist of how tests work:
+
+* The `test` sub-package contains shared test setup and helpers.
+
+* The `test.Env` type manages setting up and tearing down global test state, like the connection to PostgreSQL.
+
+* PostgreSQL is run locally (I use [Postgres.app](http://postgresapp.com)), and located via the `DATABASE_URL` environment variable.
+
+* The [`migrate`](https://github.com/mattes/migrate) package is used to create a clean database before each test.
+
+* The standard [`net/http/httptest`](https://golang.org/pkg/net/http/httptest/) package provides a test HTTP server that runs the API code.
+
+* Test requests are made using standard HTTP.
+
+Dive in and look at the tests, or [read the blog post for more detail](http://nerdyc.com/blog/2016/06/16/testing-web-apps-end-to-end-in-go/).
+ 
+## Contact Me!
+
+I'd love to know if this helps you! I'm [@nerdyc](https://twitter.com/nerdyc) on Twitter.

client.go

@@ -0,0 +1,160 @@
+package service
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"io/ioutil"
+	"net/http"
+	"net/url"
+)
+
+// Client defines the interface exposed by our API.
+type Client interface {
+	AddContact(contact AddContactRequest) (*Contact, error)
+	GetContactByEmail(email string) (*Contact, error)
+}
+
+// ErrorResponse is returned by our service when an error occurs.
+type ErrorResponse struct {
+	StatusCode int    `json:"status_code"`
+	Message    string `json:"message"`
+}
+
+func (e ErrorResponse) Error() string {
+	return fmt.Sprintf("%v: %v", e.StatusCode, e.Message)
+}
+
+// NewClient creates a Client that accesses a service at the given base URL.
+func NewClient(baseURL string) Client {
+	httpClient := http.DefaultClient
+	return &DefaultClient{
+		http:    httpClient,
+		BaseURL: baseURL,
+	}
+}
+
+// ===== DefaultClient =================================================================================================
+
+// DefaultClient provides an implementation of the Client interface.
+type DefaultClient struct {
+	http    *http.Client
+	BaseURL string
+}
+
+// performRequestMethod constructs a request and uses `performRequest` to execute it.
+func (c *DefaultClient) performRequestMethod(method string, path string, headers map[string]string, data interface{}, response interface{}) error {
+
+	req, err := c.newRequest(method, path, headers, data)
+	if err != nil {
+		return err
+	}
+
+	return c.performRequest(req, response)
+}
+
+// performRequest executes the given request, and uses `response` to parse the JSON response.
+func (c *DefaultClient) performRequest(req *http.Request, response interface{}) error {
+	// perform the request
+	httpResponse, err := c.http.Do(req)
+	if err != nil {
+		return err
+	}
+
+	defer httpResponse.Body.Close()
+
+	// read the response
+	var responseBody []byte
+	if responseBody, err = ioutil.ReadAll(httpResponse.Body); err != nil {
+		return err
+	}
+
+	if httpResponse.StatusCode >= 400 {
+		contentTypeHeader := httpResponse.Header["Content-Type"]
+		if len(contentTypeHeader) != 0 && contentTypeHeader[0] == "application/json" {
+			var errResponse ErrorResponse
+			err := json.Unmarshal(responseBody, &errResponse)
+			if err == nil {
+				return errResponse
+			}
+		}
+
+		return &ErrorResponse{
+			StatusCode: httpResponse.StatusCode,
+			Message:    httpResponse.Status,
+		}
+	}
+
+	// map the response to an object value
+	if err := json.Unmarshal(responseBody, &response); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+// newRequest builds a new request using the given parameters.
+func (c *DefaultClient) newRequest(method string, path string, headers map[string]string, data interface{}) (*http.Request, error) {
+
+	// Construct request body
+	var body io.Reader
+	if data != nil {
+		requestJSON, err := json.Marshal(data)
+		if err != nil {
+			return nil, err
+		}
+
+		body = bytes.NewReader(requestJSON)
+	}
+
+	// construct the request
+	req, err := http.NewRequest(method, c.BaseURL+path, body)
+	if err != nil {
+		return nil, err
+	}
+
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+
+	for k, v := range headers {
+		req.Header.Set(k, v)
+	}
+
+	return req, nil
+}
+
+
+
+// ----- Add Contact ---------------------------------------------------------------------------------------------------
+
+type AddContactRequest struct {
+	Email string `json:"email"`
+	Name  string `json:"name"`
+}
+
+type ContactResponse struct {
+	Contact *Contact `json:"contact"`
+}
+
+func (c *DefaultClient) AddContact(contact AddContactRequest) (*Contact, error) {
+	var response ContactResponse
+	err := c.performRequestMethod(http.MethodPost, "/contacts", nil, contact, &response)
+	if err != nil {
+		return nil, err
+	}
+
+	return response.Contact, nil
+}
+
+func (c *DefaultClient) GetContactByEmail(email string) (*Contact, error) {
+	var response ContactResponse
+	var path = fmt.Sprintf("/contacts/%v", url.QueryEscape(email))
+	err := c.performRequestMethod(http.MethodGet, path, nil, nil, &response)
+	if err != nil {
+		return nil, err
+	}
+
+	return response.Contact, nil
+}

contacts.go

@@ -0,0 +1,68 @@
+package service
+
+import "database/sql"
+
+// Contact describes a contact in our database.
+type Contact struct {
+	Id    int    `json:"id"`
+	Email string `json:"email"`
+	Name  string `json:"name"`
+}
+
+// ===== ADD CONTACT ===================================================================================================
+
+// AddContact inserts a new contact into the database.
+func (db *Database) AddContact(c Contact) (int, error) {
+	var contactId int
+	err := db.Write(func(tx *Transaction) {
+		contactId = tx.AddContact(c)
+	})
+
+	return contactId, err
+}
+
+// AddContact inserts a new contact within the transaction.
+func (tx *Transaction) AddContact(c Contact) int {
+	row := tx.QueryRow(
+		"INSERT INTO contacts (email, name) VALUES ($1, $2) RETURNING id",
+		c.Email,
+		c.Name,
+	)
+
+	var id int
+	if err := row.Scan(&id); err != nil {
+		panic(err)
+	}
+
+	return id
+}
+
+// ===== GET CONTACT ===================================================================================================
+
+// GetContactByEmail reads a Contact from the Database.
+func (db *Database) GetContactByEmail(email string) (*Contact, error) {
+	var contact *Contact
+	err := db.Read(func(tx *Transaction) {
+		contact = tx.GetContactByEmail(email)
+	})
+
+	return contact, err
+}
+
+// GetContactByEmail finds a contact given an email address. `nil` is returned if the Contact doesn't exist in the DB.
+func (tx *Transaction) GetContactByEmail(email string) *Contact {
+	row := tx.QueryRow(
+		"SELECT id, email, name FROM contacts WHERE email = $1",
+		email,
+	)
+
+	var contact Contact
+	err := row.Scan(&contact.Id, &contact.Email, &contact.Name)
+	if err == nil {
+		return &contact
+	} else if err == sql.ErrNoRows {
+		return nil
+	} else {
+		panic(err)
+	}
+}

database.go

@@ -0,0 +1,114 @@
+package service
+
+import (
+	"database/sql"
+	"fmt"
+	"log"
+)
+
+// Database wraps our SQL database. Defining our own type allows us to define helper functions on the Database.
+type Database struct {
+	DB *sql.DB
+}
+
+func (db *Database) Close() {
+	db.DB.Close()
+}
+
+// ===== TRANSACTIONS ==================================================================================================
+
+// Transaction wraps a SQL transaction. Defining our own type allows functions to be defined on the Transaction.
+type Transaction struct {
+	*sql.Tx
+	db *Database
+}
+
+type TransactionFunc func(*Transaction)
+
+func (db *Database) begin() (*Transaction, error) {
+	tx, err := db.DB.Begin()
+	if err != nil {
+		return nil, err
+	}
+
+	return &Transaction{tx, db}, nil
+}
+
+// Read begins a read-only transaction and passes it to the given function. The transaction will be rolled back after
+// the function returns. Any panics will be handled, and returned as an error.
+func (db *Database) Read(reader TransactionFunc) (err error) {
+	tx, err := db.begin()
+	if err != nil {
+		return err
+	}
+
+	// A read should always rollback the transaction
+	defer func() {
+		if rollbackErr := tx.Rollback(); rollbackErr != nil {
+			// Ignore errors rolling back
+			log.Println(rollbackErr.Error())
+		}
+	}()
+
+	// recover any panics during the transaction, and return it as an error to the caller
+	defer func() {
+		if r := recover(); r != nil {
+			var ok bool
+			err, ok = r.(error)
+			if !ok {
+				err = fmt.Errorf("Database.Read: %v", r)
+			}
+		}
+	}()
+
+	// Mark the transaction as read only
+	_, err = tx.Exec("SET TRANSACTION ISOLATION LEVEL REPEATABLE READ, READ ONLY")
+	if err != nil {
+		panic(fmt.Errorf("Unable to mark transaction read-only"))
+	}
+
+	reader(tx) // Code in this function can panic
+	return err
+}
+
+// Write begins a transaction and passes it to the given function. The transaction will be committed when the function
+// returns. If the function panics, the transaction is rolled back, and the error provided to panic is returned.
+func (db *Database) Write(writer TransactionFunc) (err error) {
+	tx, err := db.begin()
+	if err != nil {
+		return err
+	}
+
+	didPanic := false
+
+	// write operations commit or rollback the transaction
+	defer func() {
+		if didPanic {
+			if rollbackErr := tx.Rollback(); rollbackErr != nil {
+				// Ignore errors rolling back
+				log.Println(rollbackErr.Error())
+			}
+		} else {
+			if commitErr := tx.Commit(); commitErr != nil {
+				err = commitErr
+			}
+		}
+	}()
+
+	// recover any panics during the transaction, and return it as an error to the caller
+	defer func() {
+		if r := recover(); r != nil {
+			didPanic = true
+
+			var ok bool
+			err, ok = r.(error)
+			if !ok {
+				err = fmt.Errorf("Database.Write: %v", r)
+			}
+		}
+	}()
+
+	writer(tx) // If the function panics, the transaction will be rolled back
+
+	return err
+}

db/migrations/001_contacts.down.sql

@@ -0,0 +1 @@
+DROP TABLE contacts;

db/migrations/001_contacts.up.sql

@@ -0,0 +1,5 @@
+CREATE TABLE contacts (
+    id SERIAL PRIMARY KEY,
+    email varchar(255) UNIQUE NOT NULL,
+    name varchar(255) NOT NULL
+);