ph.codeberg.page

Changes on this website.

2025-12-19T00:00:00Z

There are two changes to this website worth mentioning.

First, hosting has moved from GitHub to Codeberg.

Second, I have switched from Hugo to a custom rendering engine.

I never needed the advanced functionality Hugo provides. After an upgrade, my custom theme broke and I could no longer compile this website. Instead of spending hours figuring out and fixing the issue, I decided to finally roll out my own minimal compiler. Excluding the templates, the implementation is less than 330 lines of simple Go code, with goldmark as the single dependency to convert Markdown to HTML.

The build process and deployment are handled by a bash function, which compiles the content and publishes it via a designated Git branch.

The feed URL is now https://ph.codeberg.page/feed.xml.

Routing enhancements.

2024-06-12T00:00:00Z

Go 1.22 ships with router Enhancements. The net/http.ServeMux can now match requests by method, host and a simple path wildcard.

With the new ServeMux, it is no longer necessary to struggle to find the best routing method. For most cases, standard library should be the best choice. And with the next release, you can align your declarations with any number of spaces.

func run() {
	rt := http.NewServeMux()

	rt.Handle(`POST /users`, &demoHandler{info: "create user"})
	rt.Handle(`GET  /users/{name}`, &demoHandler{info: "show user"})
	rt.Handle(`GET  /users/{name}/profile`, &demoHandler{info: "show user profile"})

	_ = http.ListenAndServe("localhost:8000", rt)
}

type demoHandler struct {
	info string
}

func (h *demoHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintln(w, h.info, r.PathValue("name"))
}

% curl localhost:8000/users
Method Not Allowed
% curl localhost:8000/users -X POST
create user
% curl localhost:8000/users/andy
show user andy
% curl localhost:8000/users/andy/profile
show user profile andy
% curl localhost:8000/users/andy/profile -X POST
Method Not Allowed

Tasks script.

2024-05-28T00:00:00Z

Every project grows to a point where a set of custom tasks must be executed on various occasions. It is good to write those commands down, so that they don't get lost and anyone can execute them. I used to maintain a Makefile as a simple way to organize and share tasks with others.

As the complexity grows, and more functionality is needed, Makefile becomes more unreadable. It feels like using the wrong tool for the job.

And indeed, there is a better tool - shell scripting.

The below Bash script is a solid base to extend, for managing a collection of tasks.

#!/usr/bin/env bash

set -euo pipefail


function task:help {
	# Print this script help.
	local tasks
	local self_path
	local desc

	printf "%s <task> [args]

Tasks:
" "${0}"
	tasks=$(compgen -A function | sed -En 's/task:(.*)//p')
	self_path=$(realpath "$0")
	for task in ${tasks}; do
		desc=$(grep "function task:$task {" "$self_path" -A 1 | sed -En 's/.*# (.*)//p')
		printf "  %-32s	%s
" "$task" "$desc"
	done
}

# shellcheck disable=SC2145
"task:${@:-help}"

In order to register a new task, define a task:<name> function. The first line, when comment, is used as that task documentation.

function task:say-hello {
  # Greet the user.
  echo "Hello $USER"
}

When the script is called with no arguments, it runs help that renders the list of available tasks with their description.

% ./run
./run <task> [args]

Tasks:
  say-hello                             Greet the user.
  help                                  Print this script help.

Testing in go.

2020-01-30T00:00:00Z

This is a collection of testing techniques and patterns that I have learned throughout my career of being a Go programmer.

`testing` package basics

The Go standard library comes with the testing package which provides a solid base for writing tests.

Each test should be a separate function. A test function must accept a single argument of type *testing.T.

A test for a functoin isEven could look like this:

func TestIsEven(t *testing.T) {
    if !isEven(2) {
        t.Fatal("2 is even")
    }
    if isEven(1) {
        t.Fatal("1 is odd")
    }
}

Run your test by using the go test command, for example

# Test this directory
$ go test .

# Test the whole project recursively.
$ go test a-package.com/path/...

Failing and messages

Each test accepts one argument, a T instance. T provides methods that allow to print information and control the flow of a test.

Use t.Log and t.Logf methods to write a message.

Use t.Error and t.Errorf methods to write a message and mark the test as failed.

Use t.Fatal and t.Fatalf methods to write a message, mark the test as failed and instantly terminate that test execution.

Write good error messages

A good error message is concise and short. Sprinkle each result with a bit of context.

if isEven(1) {
    t.Fatal("1 is an odd number")
}
if want, got := 42, compute(); want != got {
    t.Fatalf("want %d, got %d", want, got)
}

By declaring got and want I am sure that what is tested for is what I print. If the compute function was changed and in the new implementation want should be 33 I cannot make the mistake of not updating the error message. Both got and want are scoped to the if statement only.

When writing a table test, declaring an expected value might not be necessary. The expected value can be easily found in the test declaration.

Skipping a test

Some tests should run only under special circumstances. For example, you want to run a test only if a database is available. t.Skip and t.Skipf methods allow to cancel (skip) the currently running test without failing it.

func TestDatabaseIntegration(t *testing.T) {
    db, err := connectToDatabase("test-database")
    if err != nil {
        t.Skipf("cannot connect to database: %s", err)
    }
    defer db.Close()

    // ...
}

Test helpers

Often times many tests require similar dependencies, for example running a service or preparing a state. Instead of repeating the preparation code extract each functionality to a separate function.

Test helpers: Setting up dependencies

If you are testing code that depends on an external database, this is how the beginning of a test function might look like:

func TestDatabaseIntegration(t *testing.T) {
    db, err := connectToDatabase("test-database")
    if err != nil {
        t.Skipf("cannot connect to database: %s", err)
    }
    defer db.Close()
    if err := db.Ping(); err != nil {
        t.Fatalf("cannot ping database: %s", err)
    }

    for i, migration := range databaseMigrations {
        if err := db.ApplyMigration(migration); err != nil {
            t.Fatalf("cannot apply %d migration: %s", i, err)
        }
    }

    mycollection := NewCollection(db)

    // The actual test starts below.
    // ...
}

A solution to code repetition can be to create a function that will encapsulate certain functionality. The whole setup and teardown process for a test can be extracted.

func TestDatabaseIntegration(t *testing.T) {
    mycollection, cleanup := ensureMyCollection(t, "test-database")
    defer cleanup()

    // The actual test starts below.
    // ...
}

func ensureMyCollection(t testing.TB), dbName string (MyCollection, func(){} {
    t.Helper()

    db, err := connectToDatabase(dbName)
    if err != nil {
        t.Skipf("cannot connect to database: %s", err)
    }

    if err := db.Ping(); err != nil {
        db.Close()
        t.Fatalf("cannot ping database: %s", err)
    }

    for i, migration := range databaseMigrations {
        if err := db.ApplyMigration(migration); err != nil {
            db.Close()
            t.Fatalf("cannot apply %d migration: %s", i, err)
        }
    }
    collection := NewCollection(db)
    cleanup := func() {
        db.Close()
    }
    return collection, cleanup
}

With the above solution, ensureMyCollection can be used by many test functions to ensure that a collection using a database as a backend is available. A helper function hides the for the test logic irrelevant part of setting up an environment and ensuring all components are provided.

A helper function accepts testing.TB interface instead of t *testing.T. That makes it useful for both test and benchmark functions.

A helper function does not return an error. Instead, it directly terminates the test by calling t.Fatal.

At the beginning of the helper function the t.Helper() method is called. This marks this function and when it fails the stack information and error will be more helpful.

ensureMyCollection returns a cleanup function. This is a convenient way of cleaning up all created resources. The user of this helper must call it once the returned resource is not needed anymore. The cleanup function should not return anything nor fail the test.

Blackbox package testing

Test files that declare a package with the suffix "_test" will be compiled as a separate package, and then linked and run with the main test binary. -- golang.org

Test files for your package are located in the same directory as the code they test. Your tests can belong to the same package as the rest of the code. It is also possible to enforce a black-box test for your package. Your test files can be in the same directory as your package code and use a different package name.

package xxx_test

Using a different test package name enforces that only the public interface of the tested package is accessible. This is for example how strings and bytes packages are tested.

Third party test helper packages

I do not use any additional packages for testing. I am of an opinion that assert functions are not as helpful as one may think. Introducing an external package requires learning a new API.

Someone else wrote a great summary on the topic.

Complex comparisons can usually be done using reflect.DeepEqual function.

`reflect.DeepEqual`

Those values that cannot be compared with ==, most of the time can be compared with reflect.DeepEqual.

Table tests

When testing a functionality a single input is often not enough to ensure correctness. Repeating the same operation for many cases can be implemented using table tests.

Use a map with strings as keys to provide a description of each test case.

func TestDiv(t *testing.T) {
    cases := map[string]struct{
        A int
        B int
        WantRes int
        WantErr error
    }{
        "two positive numbers": {
            A: 4,
            B: 2,
            WantRes: 2,
        },
        "divide by zero": {
            A: 4,
            B: 0,
            WantErr: errors.ErrZeroDivision,
        },
    }

    for testName, tc := range cases {
        t.Run(testName, func(t *testing.T) {
            res, err := Div(tc.A, tc.B)
            if !errors.Is(err, tc.WantErr) {
                t.Fatalf("unexpected error: %q", err)
            }
            if res != tc.WantRes {
                t.Fatalf("unlexpected result: %d", res)
            }
        })
    }
}

When declaring a test case, always use field names. This increases the readability and you have to provide only non zero values.

cases := map[string]struct{
    DB *Database
    Req *Request
    WantRes int
    WantErr error
}{
    // BAD
    {nil, myrequest, 32, nil},

    // GOOD
    {
        Req: myrequest,
        WantRes: 32,
    },
}

Mocking

Write your code to accept interfaces. Using interfaces allows you to test a single layer of a functionality at a time.

For example, if you are writing an application that is storing data in an SQL database, instead of accessing the database directly through a *sql.DB instance use a wrapper. Using a data access abstraction allows for mocking.

When writing a mock you do not have to implement all methods. For the compiler it is enough to include the interface in the mock declaration. Implement only methods that you intend to call.

type Collection interface {
    One(id uint64) (*Entity, error)
    List() ([]*Entity, error)
    Add(Entity) error
    Delete(id uint64) error
}

type CollectionMock struct {
    Collection
    Err error
}

func (c *CollectionMock) Add(Entity) error {
    return c.Err
}

CollectionMock implements the Collection interface, but using any other method than Add will panic. See the full example.

Your code should provide a mock

When writing a package that is used by others provide test implementations of your interfaces.

This approach is taken by the standard library. For example, httptest.ResponseRecorder allows to test your HTTP handler without using a real http.ResponseWriter.

Test flags

You can add your own flags to the go test command in order to customize your tests. Use the flag package and declare your flags globally.

var dbFl = flag.String("db", "", "Use given database DSN.")

Environment variables

Instead of flag you can control your tests using environment variables. If you follow the 12 factor app principles then your application is already utilizing environment variables for the configuration.

var dbDSN = os.Getenv("DATABASE_DSN")

Fixtures

If your test requires fixtures /testdata is the directory you should consider keeping them in.

The go tool will ignore a directory named "testdata", making it available to hold ancillary data needed by the tests. -- golang.org

When running tests each test function is executed with its working directory set to the source directory of the tested package. That means that when accessing files in /testdata you can safely use relative path

fd, err := os.Open(filepath.Join("testdata", "some-fixture.json"))

Golden files

Golden files are a great way to validate and keep track of a test output. Together with a version control system they are much easier to maintain than strings hard coded in functions.

var goldFl = flag.Bool("gold", false, "Write result to golden files instead of comparing with them.")


func TestExample(t *testing.T) {
    // Test logic.
    result := ...

    if *goldFl {
        writeGoldenFile(t, result)
    }

    compareWithGoldenFile(t, result)
}

This technique comes in very helpful combined with table tests.

Integration tests

For a well written application integration testing should not require more work than usual testing. For each external resource provide a single function to setup and teardown the resource.

Build constraints

You can use a build constraint to conditionally build code in a file.

$ head -n 1 app_intergration_test.go
// +build integration

To run tests including those tagged as integration use -tag flag.

$ go test -tag integration .

Setup/teardown

When using the testing package, it is possible to overwrite the test main function.

Using a custom test main function allows to execute code before and after executing all discovered tests. This can be running an external dependency like a database instance or building a binary that tested functionality might depend on.

func TestMain(m *testing.M) {
    // Setup code.

    // defer Teardown code.

    os.Exit(m.Run())
}

`-race`

Run tests with -race flag to enable data race detection.

This functionality is not available on musl based systems.

Testing FAQ

Check the FAQ at golang.org.

Error handling.

2019-02-20T00:00:00Z

In Go 1.13 error wrapping was introduced as part of the standard library. This post was written before the update to the errors package.

Go is a language that does not provide exceptions. Instead, an operation can return an error. Errors are values that implement the error interface.

I have worked with several errors handling patterns over the years and I would like to summarize my experience focusing on the good solutions.

For the purpose of this post, let us imagine a very simple banking application. Accounts are represented by their numeric ID and we only know how much money each account holds. No account balance can get below zero. A bank service must implement the interface below.

type BankService interface {
    // NewAccount registers a new account in this bank. The account is
    // initialized with given funds.
    NewAccount(accountID int64, funds uint64) error

    // Transfer moves funds between two accounts. It fails if an operation
    // would cause the balance of the source account to go below zero.
    Transfer(from, to int64, amount uint64) error
}

To keep the examples short and simple an in-memory storage is used. Anything more serious would use a database instead.

Inline error creation

It is a common thing to create errors using errors.New and fmt.Errorf as they are needed. When an operation fails you can handle the failure by creating an error instance and returning it. The created error should contain information about the cause of the failure. With that in mind let us create the first version of a banking service.

{{< highlight go "hl_lines=14 24 26 30" >}} func NewBank() *Bank { return &Bank{ accounts: make(map[int64]uint64), } }

type Bank struct { accounts map[int64]uint64 }

// Create new account with given funds. Account ID must be unique. func (b *Bank) NewAccount(accountID int64, funds uint64) error { if _, ok := b.accounts[accountID]; ok { return errors.New("account exists") } b.accounts[accountID] = funds return nil }

// Transfer moves funds from one account to another. func (b *Bank) Transfer(from, to int64, amount uint64) error { switch fromFunds, ok := b.accounts[from]; { case !ok: return fmt.Errorf("source account %d not found", from) case fromFunds < amount: return fmt.Errorf("cannot transfer %d from %d account: insufficient funds", amount, fromFunds) }

if _, ok := b.accounts[to]; !ok {
    return fmt.Errorf("destination account %d not found", to)
}

b.accounts[from] -= amount
b.accounts[to] += amount
return nil

} {{< /highlight >}}

Above code presents a common way of dealing with errors. If a failure cannot be dealt with then return the error. If possible provide additional information, for example, an account ID. This is often an acceptable solution but sometimes it might not be good enough. As soon as we use the Bank instance the shortcomings are more visible.

bank := NewBank()
// ...
if err := bank.Transfer(111, 222, 10); err != nil {
    // Why did the transfer fail?
}

If the Transfer call returns an error it is not possible to learn about the reason and distinguish different cases. As a human analyzing the text message, we can tell what went wrong. If you want your code to react differently if one of the accounts does not exist and do something else when there are not enough funds on the source account then you have a problem.

Predefined errors

To provide more insights into the Transfer method failures one may declare all expected errors upfront.

For each failure case declare a corresponding error instance. Compare an error returned by the Transfer method with all error definitions it can return to discover the cause.

{{< highlight go "hl_lines=9 11 15" >}} // Transfer moves funds from one account to another. // Upon failure returns one of // ErrNoSourceAccount // ErrNoDestinationAccount // ErrInsufficientFunds func (b *Bank) Transfer(from, to int64, amount uint64) error { switch fromFunds, ok := b.accounts[from]; { case !ok: return ErrNoSourceAccount case fromFunds < amount: return ErrInsufficientFunds }

if _, ok := b.accounts[to]; !ok {
    return ErrNoDestinationAccount
}

b.accounts[from] -= amount
b.accounts[to] += amount
return nil

}

var ( // ErrNoSourceAccount is returned when the source account does not // exist. ErrNoSourceAccount = errors.New("no source account")

// ErrNoDestinationAccount is returned when the destination account
// does not exist.
ErrNoDestinationAccount = errors.New("no destination account")

// ErrInsufficientFunds is returned when a transfer cannot be completed
// because there are not enough funds on the source account.
ErrInsufficientFunds = errors.New("insufficient funds")

) {{< /highlight >}}

This is similar to how the io package deals with errors.

Returning a different error instance for each error case allows us to handle different failure cases accordingly. Test the returned error for being one of the predefined instances.

bank := NewBank()
// ...
switch err := bank.Transfer(1, 2); err {
case nil:
    println("money transferred")
case ErrNoSourceAccount:
    panic("source account does not exist")
case ErrNoDestinationAccount:
    panic("destination account does not exist")
case ErrInsufficientFunds:
    panic("not enough money")
default:
    panic("unexpected error")
}

This is in my opinion a step in the right direction but it is too verbose. This patten requires too much code to be written. You can no longer create errors when you need them. All failure cases and respective errors must be declared upfront.

In addition, you are losing the context information that you were building using fmt.Errorf. When returning ErrInsufficientFunds you no longer know which account caused it. fmt.Errorf must no longer be used for the error instance comparison to work.

Error inheritance

In Python - a language with exceptions and type inheritance - exceptions form a hierarchy. Because each error is an instance of a class belonging to that class hierarchy each exception instance can contain a custom message and be captured by its type or any type it inherits from.

This is how a banking service could be used if implemented in Python.

try:
    bank.transfer(from, to, amount)
except ErrAccountNotFound as e:
    print(e) # either source or destination account not found
except ErrInsufficientFunds:
    print("not enough money")
except Exception:
    print("unexpected condition")

Because in Python implementation both ErrNoSourceAccount and ErrNoDestinationAccount would inherit from ErrAccountNotFound, both cases can be handled with a single statement except ErrAccountNotFound.

When capturing an exception e refers to the exception instance containing the detailed information that can be helpful during debugging or consumed by the client. It can contain more information than just a human readable description.

`Causer` interface

Inheritance is not a requirement to achieve the functionality provided by Python exceptions. When considering an error it is enough if we are able to tell what was the cause of it. This is not possible with errors created using the standard library (errors or fmt packages). Instead of using the standard library, we must create our own error implementation.

What is needed is an Error structure that implements the error interface and a Wrap function that will take an error together with an additional description.

// Wrap returns an error that is having given error set as the cause.
func Wrap(err error, description string, args ...interface{}) *Error {
    return &Error{
        parent: err,
        desc:   fmt.Sprintf(description, args...),
    }
}

type Error struct {
    // Parent error if any.
    parent error
    // This error description.
    desc string
}

func (e *Error) Error() string {
    if e.parent == nil {
        return e.desc
    }
    return fmt.Sprintf("%s: %s", e.desc, e.parent)
}

In addition, it will provide a Cause method that will return the wrapped error instance or nil.

// Cause returns the cause of this error or nil if this is the root cause
// error.
func (e *Error) Cause() error {
    return e.parent
}

One more function is necessary for this to be complete. We must be able to compare an error with another error or its cause. The error interface does not provide Cause method so we must use type casting to determine if an error instance implements the causer interface.

Instead of a function a method of the Error structure provides a nicer API.


// Is returns true if given error or its cause is the same kind.
// If cause error provides Cause method then a comparison is made with all
// parents as well.
func (kind *Error) Is(err error) bool {
    type causer interface {
        Cause() error
    }
    for {
        if err == kind {
            return true
        }
        if e, ok := err.(causer); ok {
            err = e.Cause()
        } else {
            return false
        }
    }
}

Let us test the Error. All errors are created using the Wrap function which builds an error hierarchy. It is possible to attach additional information by including it in the description string.

root := Wrap(nil, "root")
child1 := Wrap(root, "child one")
child2 := Wrap(root, "child two")

fmt.Println("child 1 is root", root.Is(child1))
// child 1 is root true

fmt.Println("child 2 is root", root.Is(child2))
// child 2 is root true

fmt.Println("root is child 1", child1.Is(root))
// root is child 1 false

fmt.Println("child 2 is child 1", child1.Is(child2))
// child 2 is child 1 false

inlinedErr := Wrap(child2, "current time: %s", time.Now())
fmt.Println("inlined child 2 is root", root.Is(inlinedErr))
// inlined child 2 is root true
fmt.Println("inlined child 2 is child 2", child2.Is(inlinedErr))
// inlined child 2 is child 2 true

fmt.Println("fmt error is root", root.Is(fmt.Errorf("fmt error")))
// fmt error is root false

Above Error implementation is a powerful solution to error handling. It is easy to implement, does not require much code and it is portable without creating an explicit dependency on the causer interface.

Predefined errors with inheritance

If an error implements the causer interface we can unwind it and retrieve the previous error instance! This means that no matter how many times we will wrap an error, as long as all layers implement the causer interface we can retrieve the parent error instance.

Back to the Bank.Transfer example. All error instances were wrapped before returning and provide all the details one may expect an error to provide.

{{< highlight go "hl_lines=4 6-7 11" >}} func (b *Bank) Transfer(from, to int64, amount uint64) error { switch fromFunds, ok := b.accounts[from]; { case !ok: return Wrap(ErrNoSourceAccount, "ID %d", from) case fromFunds < amount: return Wrap(ErrInsufficientFunds, "cannot transfer %d from %d account", amount, fromFunds) }

if _, ok := b.accounts[to]; !ok {
    return Wrap(ErrNoDestinationAccount, "ID %d", to)
}

b.accounts[from] -= amount
b.accounts[to] += amount
return nil

}

var ( // ErrAccountNotFound is return when an operation fails because the // requested account does not exist. ErrAccountNotFound = Wrap(nil, "account not found")

// ErrNoSourceAccount is returned when the source account does not
// exist.
ErrNoSourceAccount = Wrap(ErrAccountNotFound, "no source")

// ErrNoDestinationAccount is returned when the destination account
// does not exist.
ErrNoDestinationAccount = Wrap(ErrAccountNotFound, "no destination")

// ErrInsufficientFunds is returned when a transfer cannot be completed
// because there are not enough funds on the source account.
ErrInsufficientFunds = Wrap(nil, "insufficient funds")

) {{< /highlight >}}

Errors can be tested on any granularity level. It is valid to compare with the high level ErrAccountNotFound or more precise ErrNoSourceAccount.

bank := NewBank()
// ...
switch err := bank.Transfer(1, 2, 100); {
case err == nil:
    println("money transferred")
case ErrNoDestinationAccount.Is(err):
    panic("destination account does not exist")
case ErrInsufficientFunds.Is(err):
    panic("not enough money " + err.Error()) // err provides more details
default:
    panic("unexpected error")
}

Don't Drink Too Much Cool Aid

What I have presented is a powerful pattern. You may use the causer interface to extract attributes or custom error implementations that were wrapped, attaching helpful information on each execution step. This might be great for example during input validation, where together with an error you want to return information about the invalid fields in a way that can be extracted later.

You can use the causer interface and the Wrap function to declare a complex tree of errors that are several layers deep and cover every possible case. If you do, think again about your use case and if such granularity is helpful. Usually, just a handful of errors declared upfront do the job better. I tend to always inline error creation first and only if a case requires more attention declare a previously inlined error.

Regardless of what you do try to avoid blindly importing any error package. Consider your use cases and try to tailor your errors implementation to suit your needs.

Cache stampede protection.

2018-09-14T00:00:00Z

Writing an application that handles concurrent traffic from a lot of clients in a performant way is not an easy task. To narrow this problem to web applications only, serving as many HTTP requests as possible in a short time is often a challenge.

In most cases of an HTTP application, optimizing access to the database can be the easiest and the best first step.

Caching database access

Using a database that provides plenty of functionality and storing data in denormalized form makes development easier. This comes at the cost of the database having to execute complex queries and do more computation in order to return a result.

Making several database queries, even simple ones, to handle a request adds up and makes our request handing slower. Even if a query is executed instantly, the database client must transfer the data over the network each time.

Most databases implement some kind of internal caching. They optimize access to popular data if the query complexity allows to do so. Why add an external cache layer in front of the database then?

A cache layer can be added to remember:

the result of a heavy query that takes time and puts heavy load on the database.
the result of a repeating query that causes the database to waste resources on returning the same data all the time.

The fastest code is the code that never runs

Imagine a very popular web application that displays the details of an item. An item is an entity identifiable by a unique number, that is rarely changing. Due to heavy traffic, the database that stores items is all the time asked about the same entity.

To offload some of the repeating requests, we introduce a cache layer. Whenever an item is needed, serve it from the cache. The database is queried only if an item does not exist in the cache.

For the purpose of this post, let us assume we have a store and a cache implementation available that implement the following interfaces. Delegating database access allows for a cache implementation that is not tightly coupled to the original implementation.

type ItemStore interface {
	// FindItem item returns an item with given ID or ErrNotFound
	FindItem(ctx context.Context, itemID int64) (*Item, error)
}

type CacheStore interface {
	// Get loads value under given key into destValue. ErrMiss is returned
	// if key does not exist.
	Get(ctx context.Context, key string, destValue interface{}) error
	// Set value of given key.
	Set(ctx context.Context, key string, value interface{}, ttl time.Duration) error
}

Instead of directly calling the database each time an item is needed, a cache layer is used.

func CacheItemStore(cache CacheStore, store ItemStore) ItemStore {
	return &cachedItemStore{
		store: store,
		cache: cache,
	}
}

type cachedItemStore struct {
	store ItemStore
	cache CacheStore
}

func (c *cachedItemStore) FindItem(ctx context.Context, itemID int64) (*Item, error) {
	cacheKey := fmt.Sprintf("item:%d", itemID)

	var item Item
	switch err := c.cache.Get(ctx, cacheKey, &item); err {
	case nil:
		return &item, nil
	case ErrMiss:
		// Not in cache, fetch from the database.
	default:
		// Cache error is not critical for providing this
		// functionality, log it and continue.
		log.Printf("cannot get from cache: %s", err)
	}

	item, err := c.store.FindItem(ctx, itemID)

	// To simplify this example, do not cache ErrNotFound. Depending on the use
	// case, remembering that an item does not exist might be desired.

	if err == nil {
		if err := c.cache.Set(ctx, cacheKey, &item, time.Minute); err != nil {
			// Cache error is not critical for providing this
			// functionality, log it and continue.
			log.Printf("cannot set in cache: %s", err)
		}
	}

	return item, err
}

Cache errors are not critical for the functionality of the FindItem method. They are logged, so that we have a good insight into our application.

To decide for how long a result can be cached and when the value must be refreshed, a domain knowledge is required.

Cache stampede problem

Adding a cache layer can reduce the amount of calls to a resource that the cache protects. Whether the resource is a database, an external service or a local computation task, the amount of communication that happens can be significantly reduced.

There are two hard things in computer science: cache invalidation, naming things, and off-by-one errors.

-- Jeff Atwood

Most cache implementations store data with an expiration time, after which it is removed. Using time to live (TTL) is an easy compromise to ensure that stored data is never too old. Instead of trying to keep track of when a certain query result is changing, remember the result for a short period to minimize the possible errors.

Cache expiration introduces a new problem. Take our example of a web application all the time displaying an item with ID 1. Hundreds of requests per second and all of them require this item's details to be served. When the item with ID 1 is served from a cache, the database can allocate resources to do something else.

Our cache is using TTL to ensure that served data is never too old. FindItem will cache the result for one minute. After one minute, the value expires (it is being removed from the cache) to force a refresh.

Keep in mind, that there are hundreds of requests happening every second. All of them need the item with ID 1 to be served. The item is not in the cache anymore, so the only place to get it is the database. This problem is called cache stampede.

The database is not being shielded by an external cache layer anymore. It also does not have its own cache ready.

Access Locking

To prevent the same query being executed multiple times when a value is not cached, we can introduce a locking mechanism. Before asking the database, acquire a "query lock".

Our lock will be implemented using a cache service. In addition to Get and Set operations, SetNx is required.

type CacheStore interface {
	Get(ctx context.Context, key string, destValue interface{}) error
	Set(ctx context.Context, key string, value interface{}, ttl time.Duration) error

	// SetNx sets the value of a given key only if it does not exist.
	// Returns ErrConflict if the key is already in use.
	SetNx(ctx context.Context, key string, value interface{}, ttl time.Duration) error
}

When FindItem is called, we first try to read the item from the cache. If the item does not exist in the cache, we either acquire a lock and get data from the database or keep checking the cache. A value will be cached by another client or we will get the lock.

func (c *cachedItemStore) FindItem(ctx context.Context, itemID int64) (*Item, error) {
	cacheKey := fmt.Sprintf("item:%d", itemID)

readFromCache:
	for {
		var item Item
		switch err := c.cache.Get(ctx, cacheKey, &item); err {
		case nil:
			return &item, nil
		case ErrMiss:
			// Not in cache, fetch from the database, but only of
			// no other client is already doing this.
			cacheKeyLock := cacheKey + ":query-lock"
			switch err := c.cache.SetNx(ctx, cacheKeyLock, 1, time.Second); err {
			case nil:
				// We own the lock, ask the database about the value.
				break readFromCache
			case ErrConflict:
				// Another process owns the lock. Wait until
				// the value is stored in the cache or the lock
				// is released and we can query the database.
				//
				// Short sleep ensures that we do not overuse
				// the cache.
				time.Sleep(25 * time.Millisecond)
				continue readFromCache
			default:
				log.Printf("cannot acquire lock in cache: %s", err)
				break readFromCache
			}
		default:
			// Cache error is not critical for providing this
			// functionality. Log it and continue.
			log.Printf("cannot get from cache: %s", err)
			break readFromCache
		}
	}

	item, err := c.store.FindItem(ctx, itemID)

	if err == nil {
		if err := c.cache.Set(ctx, cacheKey, &item, time.Minute); err != nil {
			log.Printf("cannot set in cache: %s", err)
		}
	}

	return item, err
}

Above implementation ensures that at most one client is asking the database about an item with the same ID. If more than one FindItem call is done at the same time, only one client will query the database while all others are waiting for the cached result.

Early expiration

The situation has improved for the database. But adding locking means that when a value expires from the cache, all clients must wait until one of them fills the cache. All clients waste time and server resources on waiting.

Our cache layer can be further improved by adding an early expiration functionality. If an item is cached for 1 minute, shortly before the expiration time is due, tell one of the clients that the value must be updated.

func (c *cachedItemStore) FindItem(ctx context.Context, itemID int64) (*Item, error) {
	cacheKey := fmt.Sprintf("item:%d", itemID)
	cacheKeyLock := cacheKey + ":query-lock"

readFromCache:
	for {
		var spItem stampedeProtectedItem
		switch err := c.cache.Get(ctx, cacheKey, &spItem); err {
		case nil:
			// If an early expiration time is due, acquire lock to
			// fetch item from the database.
			if spItem.refreshAt.Before(time.Now()) {
				if c.cache.SetNx(ctx, cacheKeyLock, 1, time.Second) == nil {
					break readFromCache
				}
				// If we did not get the lock, we can still
				// return the cached data. It will expire soon,
				// but it's still valid.
			}
			return &spItem.item, nil
		case ErrMiss:
			// Not in cache, fetch from the database, but only of
			// no other client is already doing this.
			switch err := c.cache.SetNx(ctx, cacheKeyLock, 1, time.Second); err {
			case nil:
				// We own the lock, ask the database about the value
				break readFromCache
			case ErrConflict:
				// Another process owns the lock. Wait until
				// the value is stored in the cache or the lock
				// is released and we can query the database.
				//
				// Short sleep ensures that we do not overuse
				// the cache.
				time.Sleep(25 * time.Millisecond)
				continue readFromCache
			default:
				log.Printf("cannot acquire lock in cache: %s", err)
				break readFromCache
			}
		default:
			log.Printf("cannot get from cache: %s", err)
			break readFromCache
		}
	}

	item, err := c.store.FindItem(ctx, itemID)

	if err == nil {
		spItem := stampedeProtectedItem{
			refreshAt: time.Now().Add(55 * time.Second),
			item:      item,
		}
		if err := c.cache.Set(ctx, cacheKey, &spItem, time.Minute); err != nil {
			log.Printf("cannot set in cache: %s", err)
		}
	}

	return item, err
}

type stampedeProtectedItem struct {
	refreshAt time.Time
	item      *Item
}

Conclusion

Caching data that is often read can increase performance of an application. Data caching is more complicated than it might look like at first sight.

Above cache stampede protection code example is tightly coupled to ItemStore.

Accessing data in go.

2018-09-02T00:00:00Z

When writing a web application, we have to decide how to access data. Where to get it from, how to store it, how to manipulate it. Storage engines can vary, from being a single SQLite file to cache server or even an external service exposing an API.

There are many ways this topic can be addressed. I will explain how a simple and straightforward solution can be evolved into a more sophisticated one.

For the purpose of this article, let's assume that our storage engine is an SQL database with an items table. Our task is to build an endpoint, which returns a list of all items in the database. Item is an entity with a name and an ID. It can be represented by the structure below.

type Item struct {
	ID   int64
	Name string
}

First iteration

Let's start with a basic HTTP handler. To avoid global variables, let's use dependency injection. ItemListHandler takes as a parameter what's necessary for the endpoint to complete our task -- a database connection and a template. In return we are getting an HTTP handler function.

func ItemListHandler(
	db *sql.DB,
	tmpl *template.Template,
) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		// handler's code below
	}
}

To list all items, we must first query the database. Once we will read all returned rows, we can use the collected entries to render the template and send the result back.

rows, err := db.QueryContext(r.Context(), `SELECT id, name FROM items`)
if err != nil {
	http.Error(w, "Server Error", http.StatusInternalServerError)
	return
}
defer rows.Close()

var items []*Item
for rows.Next() {
	var it Item
	if err := rows.Scan(&it.ID, &it.Name); err != nil {
		http.Error(w, "Server Error", http.StatusInternalServerError)
		return
	}
	items = append(items, &it)
}
if err := rows.Err(); err != nil {
	http.Error(w, "Server Error", http.StatusInternalServerError)
	return
}

_ = tmpl.Execute(w, items)

(To simplify the example, returned error pages are very basic, we do not log errors and we are assuming that template rendering never fails.)

There are many issues with the approach presented above.

Every time we want to get the list of items, we must directly interact with the database. We must know about the database structure and in case of schema changes, we must locate all those places and update them.
Everything is implemented in a single place. Because we directly access the database, to test this code, a database must be available, it's schema prepared and test data inserted.
If we wanted to add a cache layer or some form of monitoring like tracing or metrics, we would have to add more code directly inside of the handler. That makes the code of the handler larger and testing harder. We can no longer test functionalities separately.

Second iteration

Instead of writing all the code in an HTTP handler, let's extract a part of it as a function. We can encapsulate fetching items and hide the database connection from the user.

The same code that was written directly inside of the handler is now provided by the ListItems method.

// NewItemStore returns a store for items.
func NewItemStore(db *sql.DB) *ItemStore {
	return &ItemStore{db: db}
}

type ItemStore struct {
	db *sql.DB
}

// ListItems returns all stored items.
func (is *ItemStore) ListItems(ctx context.Context) ([]*Item, error) {
	rows, err := db.QueryContext(ctx, `SELECT id, name FROM items`)
	if err != nil {
		return nil, fmt.Errorf("cannot select items: %s", err)
	}
	defer rows.Close()

	var items []*Item
	for rows.Next() {
		var it Item
		if err := rows.Scan(&it.ID, &it.Name); err != nil {
			return nil, fmt.Errorf("cannot scan item: %s", err)
		}
		items = append(items, &it)
	}
	if err := rows.Err(); err != nil {
		return nil, fmt.Errorf("scanner: %s", err)
	}
	return items, nil
}

Having such a store available, we no longer have to directly query the database in our handler. Instead of accepting *sql.DB as an argument, ItemListHandler can now take *ItemStore. Handler's body can be simplified to just a few lines.

func ItemListHandler(
	itemStore *ItemStore,
	tmpl *template.Template,
) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		items, err := itemStore.ListItems(r.Context())
		if err != nil {
			http.Error(w, "Server Error", http.StatusInternalServerError)
		}
		_ = tmpl.Execute(w, items)
	}
}

Having this handler, we no longer have to track changes to the database schema. All details of accessing item data are now in ItemStore. If you need to create or update an item, add CreateItem and UpdateItem methods.

Third iteration

Using *ItemStore for accessing items solved the first issue. Listing items is now an easy task that takes only a few lines of code.

The last change is to use an interface instead of accepting a structure pointer. Let's call our interface ItemStore. The previous implementation using an SQL database is renamed to sqlItemStore.

type ItemStore interface {
	ListItems(context.Context) ([]*Item, error)
}

// NewItemStore returns a store for items that is using an SQL database
// as a storage engine.
func NewSQLItemStore(db *sql.DB) ItemStore {
	return &sqlItemStore{db: db}
}

type sqlItemStore struct {
	db *sql.DB
}

func (s *sqlItemStore) ListItems(ctx context.Context) ([]*Item, error) {
	// ...
}

func ItemListHandler(
	itemStore ItemStore,
	tmpl *template.Template,
) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		// ...
	}
}

Defining interfaces together with the implementation might feel counterintuitive in Go. In most cases, it is better to declare an interface where it is used (not where it is implemented) to help to decouple functionalities and avoid dependencies.

In this case we do not use an interface to encourage different ItemStore implementations. Code that is used for accessing items could be put in it's own package and provide all necessary functionality -- an interface, the main implementation using an SQL database, a mock implementation for testing and more.

Mocking for tests

The sqlItemStore implementation is easy to test independently from any HTTP handler that is using it. Any handler that is using an ItemStore should also be testable without the need for any particular ItemStore implementation.

When testing handlers, instead of providing a real ItemStore implementation, we can use a mock.

type ItemStoreMock struct {
	Items []*Item
	Err   error
}

// ensure mock always implements the ItemStore
var _ ItemStore = (*ItemStoreMock)(nil)

func (mock *ItemStoreMock) ListItems(context.Context) ([]*Item, error) {
	return mock.Items, mock.Err
}

ItemStoreMock gives us full control over its API. We control what each method returns, which means we are able to test all cases we want.

Caching

Using an interface, allows us to wrap a store with additional functionality. For example, we can provide a cache layer, that will be invisible to the user. It can be added or removed without any changes to handler or store implementations.

type CacheStore interface {
	// Get loads value under given key into destValue. ErrMiss is returned
	// if key does not exist.
	Get(ctx context.Context, key string, destValue interface{}) error
	// Set value of given key.
	Set(ctx context.Context, key string, value interface{}, ttl time.Duration) error
}


func CacheItemStore(cache CacheStore, store ItemStore) ItemStore {
	return &cachedItemStore{
		cache: cache,
		store: store,
		ttl:   5 * time.Minute,
	}
}

type cachedItemStore struct {
	cache CacheStore
	store ItemStore
	ttl   time.Duration
}

func (c *cachedItemStore) ListItems(context.Context) ([]*Item, error) {
	var items []*Item
	switch err := c.cache.Get(ctx, "items:all", &items); err {
	case nil:
		return items, nil
	case ErrMiss:
		// all good, just not in the cache
	default:
		// log the error and continue
	}

	items, err := c.store.ListItems(ctx)

	if err == nil {
		if err := c.cache.Set(ctx, "items:all", items, c.ttl); err != nil {
			// log the error and continue
		}
	}

	return items, err
}

Testing of the cachedItemStore can be done using ItemStoreMock and an in-memory cache backend.

Conclusion

Writing data managers requires more effort, but allows to separate business logic from storage implementation. Separation of concerns gives us more control over data.

Thanks to using Go interfaces, we can mock and extend functionality of the storage implementation. Integration with cache or monitoring tools is easy, pluggable and can be tested separately.

ph.codeberg.page

Changes on this website.

Routing enhancements.

Tasks script.

Testing in go.

testing package basics

Failing and messages

Write good error messages

Skipping a test

Test helpers

Test helpers: Setting up dependencies

Blackbox package testing

Third party test helper packages

reflect.DeepEqual

Table tests

Mocking

Your code should provide a mock

Test flags

Environment variables

Fixtures

Golden files

Integration tests

Build constraints

Setup/teardown

-race

Testing FAQ

Error handling.

Inline error creation

Predefined errors

Error inheritance

Causer interface

Predefined errors with inheritance

Don't Drink Too Much Cool Aid

Cache stampede protection.

Caching database access

The fastest code is the code that never runs

Cache stampede problem

Access Locking

Early expiration

Conclusion

Accessing data in go.

First iteration

Second iteration

Third iteration

Mocking for tests

Caching

Conclusion

`testing` package basics

`reflect.DeepEqual`

`-race`

`Causer` interface