Go Patterns and Practices

2022-09-19

Abhinav Gupta

Hi

I’m Abhinav.

I work on Go frameworks.

Let’s talk about writing Go.

Agenda

Rules
Why
Patterns
Practices

Rules

Exported means forever
Function types are fixed
Interfaces are immutable

Exported means forever

Cannot remove

functions
variable
type
constants

once exported

Function types are fixed

Cannot modify

function
or
method

signatures

 func DeleteUser(
   ctx context.Context,
   name string,
+  softDelete bool,
 ) (...)

adding a parameter

 func DeleteUser(...) (
  deleted bool,
+ uuid uuid.UUID,
  err  error,
 )

or a return value

// ERROR
// - missing parameter: softDelete
// - cannot assign 3 values to 2 variables
deleted, err := DeleteUser(ctx, name)
if err != nil {
  // ...
}

breaks existing callers

Variadic arguments

 func ListPosts(
   ctx context.Context,
+  skipAuthors ...string
 ) ([]*Post, error)

This is fine, right?

posts, err := ListPosts(ctx)
if err != nil {
  // ...
}

Nope!

func Process(
  ctx context.Context,
  listPosts func(...) ([]*Post, error)
) {
  posts, err := listPosts(ctx)
  // ...
}

Breaks function references

Process(ctx, ListPosts)
// ERROR:
// want func(Context) (...)
//  got func(Context, ...string) (...)

Interfaces are immutable

Cannot

modify
remove
add

methods

Adding methods to an interface

 type Writer interface {
   WriteBytes([]byte) error
+  WriteString(string) error
 }

func WriteTo(w Writer) error {
  // ...
}

breaks existing implementations

type myWriter struct{ /* ... */ }

func (w *myWriter) WriteBytes(
  b []byte,
) error {
  // ...
}

// ERROR:
// does not implement WriteString
err := WriteTo(&myWriter{...})
if err != nil {
  // ...
}

Rules

Exported means forever
Function types are fixed
Interfaces are immutable

Patterns

Exported means forever

Be deliberate
You can always export it later

Function types are fixed

How to plan for expansion?

Parameter Objects

 type DeleteUserRequest struct {
   Name       string
+  SoftDelete bool
 }

func DeleteUser(
  ctx context.Context,
  req DeleteUserRequest,
) (...) {
  // ...
}

struct exclusively for parameters except Context

New optional fields

Need more than 3 parameters?
Use a struct.

Your first point of expansion comes from using parameter objects.

That’s just another way of saying that you should define a struct specifically for your function’s parameters.

This is important. The struct is not for sharing with other functions. This is not a general purpose User type for the application. This is a struct whose sole purpose is to plumb arguments to this function.

All arguments, except context, that is. If that’s an argument to your function, keep that as a separate argument — the first one.

Add new optional arguments to your function by adding new fields to this struct. This is completely backwards compatible.

As a general rule of thumb: if your function takes more than three parameters, it will inevitably need more. Use a parameter object.

That takes care of new arguments. What about new results? You guessed it.

Result Objects

 type DeleteUserResponse struct {
   Deleted bool
+  UUID    uuid.UUID
 }

func DeleteUser(
  ...
) (DeleteUserResponse, error) {
  // ...
}

struct exclusively for returns except error

New fields for new outputs

Need more than 2 results?
Use a struct.

Functional Options

type Option /* ... */

func SkipAuthors(
  names ...string,
) Option { /* ... */ }

func ListPosts(
  ctx context.Context,
  opts ...Option,
) ([]*Post, error)

ListPosts(ctx)

ListPosts(ctx,
  SkipAuthors(...),
)

type Option /* ... */

func SkipAuthors(
  names ...string,
) Option { /* ... */ }

func Archived(
  bool,
) Option { /* ... */ }

func ListPosts(
  ctx context.Context,
  opts ...Option,
) ([]*Post, error)

ListPosts(ctx)

ListPosts(ctx,
  Archived(true),
  SkipAuthors(...),
)

ListPosts(ctx,
  Archived(false),
)

Zero argument default
Required positional arguments

Don’t

Required options
Mix with parameter objects

How to implement functional options

Setup

type options struct {
}

type Option interface {
  apply(*options)
}

Add an option

type options struct {
  skipAuthors []string
}

type Option interface {
  apply(*options)
}

func SkipAuthors(
  xs ...string,
) Option {
  return skipAuthors(xs)
}

type skipAuthors []string

func (o skipAuthors) apply(...) {
  opts.skipAuthors = []string(o)
}

Add other options

type options struct {
  skipAuthors []string
  archived    bool
  postedAfter time.Time
}

type Option interface {
  apply(*options)
}

func SkipAuthors(
  xs ...string,
) Option { /* ... */ }

func Archived(
  archived bool,
) Option { /* ... */ }

func PostedAfter(
  postedAfter date.Date,
) Option { /* ... */ }

Consume the options

type options struct {
  skipAuthors []string
  archived    bool
  postedAfter time.Time
}

type Option interface {
  apply(*options)
}

func ListPosts(
  ctx context.Context,
  os ...Option,
) (...) {
  var opts options
  for _, o := range os {
    o.apply(&opts)
  }
  if opts.archived {
    // ...
  }

Return new results

type options struct {
  skipAuthors []string
  archived    bool
  postedAfter time.Time
  queryStats *Stats
}

type Stats struct {
  Elapsed time.Duration
  /* ... */
}

func QueryStats(*Stats) Option {
  /* ... */
}

var stats Stats
posts, err := ListPosts(ctx,
  QueryStats(&stats),
)
if err != nil {
  // ...
}

log.Printf(
  "Query took %v", stats.Elapsed)
// Output:
// Query took 100ms

Summary

Add new parameters or results
Compose options together
```
func(...Option) Option
```

High flexibility and high boilerplate

Okay, that was a lot about functional options. In summary, functional options let you do a lot.

add new parameters
produce new results
compose options together — this is when you take a list of Options and return a new option

But functional options also come with a lot of boilerplate. So use them only if the boilerplate is worth it.

As an aside, I mentioned earlier that there are multiple ways to implement functional options, and that I’m demonstrating my preferred approach.

There’s another approach based on function references that reduces the boilerplate a little, but I recommend you stick with the interface-based approach:

the function reference version doesn’t reduce the boilerplate that much
but it loses some really good debugging and testing properties of the interface based approach

With the interface based approach, you can actually make all your options printable, which aids in debugging, as well as comparable, which helps in testing. On top of that, the interface approach also provides you more flexibility — options shared between functions, an upgrade path for the future, and probably more that I can’t recall yet.

So just in short: if you’re going to use functional options, use the interface based approach.

Plan for function expansion

Parameter Objects
Result Objects
Functional Options
New Functions

Interfaces are immutable

How to plan for expansion?

Keep interfaces small

Bad

type Writer interface {
  WriteBytes([]byte) error
  WriteString(string) error
}

func (w *myWriter) WriteString(
  s string,
) error {
  return w.WriteBytes([]byte(s))
}

Good

type Writer interface {
  WriteBytes([]byte) error
}

func WriteString(
  w Writer, s string,
) error {
  return w.WriteBytes([]byte(s))
}

No helper methods — use functions

Well, the first thing we do is preemptive. Keep the interface small.

This ties into the thing I said earlier about being deliberate about what you export. Also be deliberate about what you add to an interface.

In this example, I have a Writer interface that defines two methods: WriteBytes and WriteString.

Except that for the majority of cases, WriteString is likely to be implemented like that — by converting the string to a byte slice, and calling WriteBytes.

Cases where it doesn’t do that are going to be rare. Yet, every implementation will have to have that same copy pasted snippet.

A solution here is to remove the method from the interface. Move it to a top level function.

This makes the interface smaller, and avoids the need to copy paste the implementation everywhere.

But this loses us the ability to customize WriteString for the few cases where it doesn’t have that implementation, where it has a more optimized solution than this.

Is there a way to get that ability back? There sure is!

Upcast to upgrade

type Writer interface {
  WriteBytes([]byte) error
}

func WriteString(w Writer, s string) error {
  return w.WriteBytes([]byte(s))
}

Add a new interface

type Writer interface {
  WriteBytes([]byte) error
}

type StringWriter interface {
  WriteString(string) error
}

func WriteString(w Writer, s string) error {
  return w.WriteBytes([]byte(s))
}

Upcast and use implementation

type Writer interface {
  WriteBytes([]byte) error
}

type StringWriter interface {
  WriteString(string) error
}

func WriteString(w Writer, s string) error {
  if sw, ok := w.(StringWriter); ok {
    return sw.WriteString(s)
  }
  return w.WriteBytes([]byte(s))
}

io/fs

type FS interface{
  Open(string) (File, error)
}

func Stat(fs FS, name string) (FileInfo, error) {
  f, err := fs.Open(name)
  if err != nil {
    return nil, err
  }
  return f.Stat()
}

io/fs

type FS interface{
  Open(string) (File, error)
}

type StatFS interface {
  FS

  Stat(string) (FileInfo, error)
}

func Stat(fs FS, name string) (FileInfo, error) {
  if sf, ok := fs.(StatFS); ok {
    return sf.Stat(name)
  }

  f, err := fs.Open(name)
  if err != nil {
    return nil, err
  }
  return f.Stat()
}

io/fs

type FS interface{
  Open(string) (File, error)
}

type ReadFileFS interface {
  FS

  ReadFile(string) ([]byte, error)
}

func ReadFile(fs FS, name string) ([]byte, error) {
  if rf, ok := fs.(ReadFileFS); ok {
    return rf.ReadFile(name)
  }

  f, err := fs.Open(name)
  if err != nil {
    return nil, err
  }
  return io.ReadAll(f)
}

Summary

Pros

DRY implementation
Upgrade as needed

Cons

No internal state
Wrapping breaks overrides

So, in summary, besides helping keeping your interface small, this pattern

Keeps your implementation DRY: you don’t have to implement a method if you don’t need to override its behavior. You have a guaranteed fallback behavior.
You can add the ability to upcast to an interface as needed. You don’t need to front load them. Add new upgrade paths as they become necessary.

But it’s not all pros. There are some limitations.

With this pattern, you do not have the ability to store any internal state from the helper function since you’re operating strictly on interface values. There’s no object for you to put private information inside.
- For example, as a convoluted use case, if my WriteString function earlier wanted to cache the byte slices it was generating, or keep count of the total number of bytes it had written, it would not be able to do that because it would have nowhere to store that information.
The second, more significant limitation of this pattern is that if someone wraps my Writer implementation, but neglects to add the WriteString method which defines the upgrade path, then that optimization is lost. Any calls to the WriteString function with the wrapped Writer will use the fallback behavior because the wrapped Writer doesn’t provide the WriteString method upgrade.

Overall, this pattern is still great. Use it for small, simple interfaces that won’t need too much state.

For other cases, there’s another option.

Driver Interface

type Driver interface {
  WriteBytes([]byte) error
}

type Writer struct{ drv Driver }

func (w *Writer) WriteBytes(bs []byte) error {
  return w.drv.WriteBytes(bs)
}

type Writer struct{ drv Driver }

func (w *Writer) WriteBytes(bs []byte) error {
  return w.drv.WriteBytes(bs)
}

func (w *Writer) WriteString(bs []byte) error {
  return w.WriteBytes([]string(bs))
}

type StringWriter interface {
  WriteString(string) error
}

type Writer struct{ drv Driver }

func (w *Writer) WriteBytes(bs []byte) error {
  return w.drv.WriteBytes(bs)
}

func (w *Writer) WriteString(bs []byte) error {
  if sw, ok := w.drv.(StringWriter); ok {
    return sw.WriteString(s)
  }
  return w.WriteBytes([]string(bs))
}

Benefits

Implement a small interface
Consume a large surface
Store internal state

Examples

zap.Logger wraps zapcore.Core
http.Client wraps http.RoundTripper
database/sql wraps database/sql/driver

Practices

Goroutines

Lightweight concurrency
but not free

Each goroutine costs at least 2 KB ^[1]

1. runtime/stack.go L72, L1479

Lifetime control

All goroutines

must finish or
must be stoppable

Do not fire-and-forget

Bad

go func() {
  for {
    flush()
    time.Sleep(delay)
  }
}()

Cannot be stopped

Good

stop := make(chan struct{})
go func() {
  tick := time.NewTicker(delay)
  defer tick.Stop()
  for {
    select {
    case <-tick.C:
      flush()
    case <-stop:
      return
    }
  }
}()

Stop with close(stop)

This is a simple worker goroutine. It runs forever, and periodically flushes something somewhere. It cannot be stopped. This is bad.

This needs to be stoppable. Let’s make it that.

I’m making use of two new things here:

I switched the time.Sleep-in-a-loop to a time.Ticker. It’s about the same in that it’ll "tick" at the same frequency, but it gives me the ticks in a channel instead of just blocking my goroutine. This lets me select on it.
Which brings me to the second piece. I’ve introduced an empty channel named stop. My goroutine selects between this and the ticker. The case for the stop channel will resolve when I close the channel, which tells the goroutine it’s time to exit.

Note that I defer a tick.Stop — when the goroutine exits, it’ll also stop the ticker. Otherwise it would keep trying to send ticks to the channel.

This is good. But it can be better.

Bad

go func() {
  for {
    flush()
    time.Sleep(delay)
  }
}()

Cannot be stopped

Better

ctx, cancel := /* ... */
go func() {
  tick := time.NewTicker(delay)
  defer tick.Stop()
  for {
    select {
    case <-tick.C:
      flush(ctx)
    case <-ctx.Done():
      return
    }
  }
}()

Stop with cancel()

The only change I’ve made here is, instead of a hand-managed stop channel, I’m relying on context.Context.

I build a context — whether with context.WithCancel or with context.WithTimeout — and get back a context and a cancel function. The context has a "done" channel that is accessible with the Done method. The "done" channel resolves when the context has finished. The context is considered to have finished when someone calls cancel, or if it had a timeout, when the timeout passes — whichever comes first.

So our goroutine now selects between the context’s Done channel and the ticker.

Why is this better? Because it gives us a context scoped to the lifetime of this goroutine. I can pass that context down to flush, which can then pass it down to any other function it calls. Any work those functions do, they can try to scope it to the context’s lifetime. If the context has expired, it means that the caller doesn’t care about the result anymore, so they don’t need to do the work that’s going to be thrown away anyway.

What if I need fire-and-forget?

Use a worker pool

func worker(
  jobc <-chan job,
) {
  for job := range jobc {
    job.do()
  }
}

Runs until close(jobc)

type manager struct {
  jobc chan<- job
}

mgr := manager{
  jobc: jobc,
}
for i := 0; i < NumWorkers; i++ {
  go worker(jobc)
}

func (m *manager) Stop() {
  close(m.jobc)
}

I set up a worker function. This pulls jobs off a channel and runs them. This worker runs until there is no more work — the channel is empty and closed. That’s what the range jobc does here.

Next I add a manager type that holds a reference to the other end of the channel. The manager feeds work into the channel based on an external signal, like a function that feeds it a request to shadow.

The manager has the ability to close the channel, signaling to all workers that it’s time to stop working.

This is a pretty basic worker pool and orchestrator setup. In this scenario, workers will run until all work has finished, and the manager has closed the channel.

What if we want them to be able to exit early? As close as possible to when the manager calls Stop? We can use context to scope the lifetimes like we did before.

func worker(
  ctx context.Context,
  jobc <-chan job,
) {
  for {
    select {
    case <-ctx.Done():
      return
    case job := <-jobc:
      job.do(ctx)
    }
  }
}

Runs until close(jobc).

type manager struct {
  stop context.CancelFunc
  jobc chan<- job
}

ctx, cancel := context.WithCancel(..)
mgr := manager{
  stop: cancel,
  jobc: jobc,
}
for i := 0; i < NumWorkers; i++ {
  go worker(ctx, jobc)
}

func (m *manager) Stop() {
  m.stop()
}

func worker(
  ctx context.Context,
  jobc <-chan job,
  wg   *sync.WaitGroup,
) {
  defer wg.Done()
  for {
    select {
    case <-ctx.Done():
      return
    case job := <-jobc:
      job.do(ctx)
    }
  }
}

type manager struct {
  stop context.CancelFunc
  jobc chan<- job
  wg   sync.WaitGroup
}

ctx, cancel := context.WithCancel(..)
mgr := manager{
  stop: cancel,
  jobc: jobc,
}
mgr.wg.Add(NumWorkers)
for i := 0; i < NumWorkers; i++ {
  go worker(ctx, jobc, &mgr.wg)
}

func (m *manager) Stop() {
  m.stop()
  m.wg.Wait()
}

Here, I’ve added a WaitGroup field to the manager. I initialize it with the number of workers right before I spawn them. Each worker calls done when it exits, informing the wait group that it finished running. The manager is able to use this in manager.Stop to wait for all workers to exit. This way, the manager doesn’t stop until all workers have stopped.

We can keep going on this. This can get more or less complicated based on your needs.

You can use a buffered channel with an estimate of your workload.
You can use an unbuffered channel with an unbounded in-memory queue of work, that you feed into the channel when there’s room.
You can use an adaptive worker pool — spawning workers on demand if there is some number of tasks outstanding and no workers to handle them.
You can emit metrics on the size of your queue to measure whether your system is able to keep up with the demand.
And several other things.

Regardless, you don’t need to start goroutines without knowing when they’ll stop.

Moving on.

Errors

Produce errors

Leaf errors

Not a leaf error

out, err := f()
if err != nil {
  return err
}

out, err := g()
if err != nil {
  return fmt.Errorf("g: %v", err)
}

Leaf errors

return errors.New("great sadness")

return fmt.Errorf(
  "unhappy result %q", result)

Can they be handled?

Use fmt.Errorf / errors.New

return errors.New("session is closed")

return fmt.Errorf(
  "invalid email address %q", email)

Yes

Sentinel errors
Structured errors

Sentinel errors

Global error variables

package fs

var ErrNotExist =
  errors.New("file does not exist")

var ErrExist =
  errors.New("file already exists")

var ErrPermission =
  errors.New("permission denied")

Prefix name with "Err"
Avoid overly verbose names (ErrFileAlreadyExists)

Match with errors.Is

if errors.Is(err, fs.ErrNotExist) {
  createFile(..)
}

Structured errors

Error types

type SyntaxError struct {
  Line, Column int
  msg          string
}

func (e *SyntaxError) Error() string

Suffix with "Error"
Use a pointer receiver

Match with errors.As

var synErr *SyntaxError
if errors.As(err, &synErr) {
  highlight(synErr.Line)
}

Structured errors, on the other hand, are just types that implement the error interface. These types typically contain some exported fields, that users can extract information from.

Use these when you’d like to explore richer information about the failure mode. For example,
- If you’re writing a parser, and want to make the line and column number of the syntax error programmatically accessible — presumably to let a text editor go to that line.
- If some uniqueness check finds a conflict, and you want to expose information about the conflicting entry.

With structured errors,

Suffix the name with "Error". Note that this is different from the "Err" prefix on sentinel errors. This, again, is a standard convention, and exceptions should be rare.
Always use a pointer receiver when defining the Error() method on these. This makes instances of these errors comparable against each other by comparing their pointer values — this is necessary for equivalence matching.

Once you have this set up, users can use errors.Is to match specific instances of this, but more commonly they’ll use errors.As to match with these by type, and extract information they need for their program.

Consume errors

Propagate:

return to caller

Handle:

react to it

Propagate errors

out, err := f()
if err != nil {
  return err
}

out, err := g()
if err != nil {
  return fmt.Errorf("get g: %w")
}

Use %w to retain error matching

type FooError struct {
  ID  string
  Err error
}

func (e *FooError) Unwrap() error {
  return e.Err
}

out, err := h(id)
if err != nil {
  return &FooError{ID: id, Err: err}
}

Add Unwrap() to retain error matching

Error messages

No "failed to X"

fmt.Errorf("failed to load config: %w", err) // BAD
// failed to load config: failed to decode protobuf: ...

fmt.Errorf("load config: %w", err)           // GOOD
// load config: decode protobuf: ...

Use %q

fmt.Errorf("get user %v: %w", user, err) // BAD
// get user : invalid name

fmt.Errorf("get user %q: %w", user, err) // GOOD
// get user "": invalid name

Don’t capitalize

fmt.Errorf("Send request: %w", err) // BAD
// Send request: Connect to "foo": ...

fmt.Errorf("send request: %w", err) // GOOD
// send request: connect to "foo": ...

Handle errors

sentinel errors ⇒ errors.Is

func loadConfig(..) (*Config, error) {
  f, err := os.Open(name)
  if err != nil {
    if errors.Is(err, fs.ErrNotExist) {
      // Use default configuration
      // if file does not exist.
      return _defaultConfig, nil
    }

    // Fail on all other errors.
    return nil, err
  }
  defer f.Close()

  // ...
}

structured errors ⇒ errors.As

c, err := connect()
if err != nil {
  var dnsErr *net.DNSError
  if errors.As(err, &dnsErr) && len(conns) {
    // Fallback to a random existing
    // connection, if any, if DNS resolution
    // failed.
    log.Warn(..., dnsErr.Name)
    c = conns[rand.Intn(len(conns))]
  } else {
    // Fail on all other errors.
    return nil, err
  }
}

Handling errors.

I’ve already covered this a little already so I won’t spend too long on this, but if you’re handling errors, you’ve got two options depending on the kind of error.

If you’re handing sentinel errors, use errors.Is.

In this example, I’m matching the "file does not exist" error with errors.Is. If it’s that error, I have a good fallback behavior: use a default configuration. If it’s not that error, then this function can’t do anything else about it. Return it upstream and make it the caller’s problem. They may catch and handle more of the error scenarios.

Similarly, if you need to handle structured errors, use errors.As.

In this example, I’m checking if the failure was a DNS error with errors.As. If it’s a DNS error and I have a non-empty list of extant connections, I’ll log the error and fall back to picking one of those at random. If it’s any other error, or I don’t have any connections, I again return the error upstream and make it the caller’s problem.

Summary

Use sentinel and structured errors when needed
fmt.Errorf and errors.New otherwise
Match with errors.Is and errors.As to handle

Conclusion

Don’t

export until necessary
fire-and-forget goroutines
noisy error messages

plan for expansion
control goroutine lifetimes
expose and handle errors

Discussion

Gopher image credits: egonelbre/gophers