talk.slide

Functional Options in Go
Inspired by Dave Cheney


Derek Perkins
Nozzle
https://nozzle.io
@derek_perkins
derek@derekperkins.com

* Let's build an api to query NYTimes articles

_Derived_from_
.link http://gtkesh.com/functional-options-for-friendly-apis-nyt-articles-api-wrapper/

You start with the simplest api

   Query(c context.Context, searchTerm string) ([]Articles, error) {
      // build a url 
      // make a request to NYT API
      // handle response
      // return articles
   }

*Usage*

  Query(c, "gophers")

* BREAKING CHANGE: Filter by beginning date

Then someone wants to filter by the date

   Query(c context.Context, searchTerm string, startDate time.Time) ([]Articles, error) {
      // build a url 
      // make a request to NYT API
      // handle response
      // return articles
   }

*Usage*

  Query(c, "gophers", time.Now().UTC().AddDate(-1, 0, 0))

* BREAKING CHANGE: Filter by beginning date but default to 1 year ago

How do you know when to use defaults vs user provided values?

- allow for nil startDate

- check for startDate.IsZero(), which isn't obvious

   Query(c context.Context, searchTerm string, startDate *time.Time) ([]Articles, error) {
      if startDate == nil {
         startDate = &time.Now().UTC().AddDate(-1, 0, 0)
      }

      // build a url 
      // make a request to NYT API
      // handle response
      // return articles
   }

*Usage*

  Query(c, "gophers", nil)

* BREAKING CHANGE: Filter by end date

Then someone wants to filter by the date

   Query(c context.Context, searchTerm string, startDate, endDate *time.Time) ([]Articles, error) {
      if startDate == nil {
         startDate = &time.Now().UTC().AddDate(-1, 0, 0)
      }

      if endDate == nil {
         endDate = &time.Now().UTC()
      }

      // build a url 
      // make a request to NYT API
      // handle response
      // return articles
   }

*Usage*

  Query(c, "gophers", time.Now().UTC().AddDate(-1, 0, 0), time.Now().UTC())

* BREAKING CHANGE: Add sorting

Now people are asking to change the sorting options

   Query(c context.Context, searchTerm string, startDate, endDate *time.Time, sortBy string) ([]Articles, error) {
      if startDate == nil {
         startDate = &time.Now().UTC().AddDate(-1, 0, 0)
      }

      if endDate == nil {
         endDate = &time.Now().UTC()
      }

      switch sortBy {
         ...
      }
      ...
   }

*Usage*

  Query(c, "gophers", time.Now().UTC().AddDate(-1, 0, 0), time.Now().UTC(), "dateDescending")

* How can you define an api for a constantly moving target?

* First thought, use specialized functions, à la Server

   QueryByStartDate(c context.Context, searchTerm string, startDate *time.Time) ([]Articles, error)

   QueryByEndDate(c context.Context, searchTerm string, endDate *time.Time) ([]Articles, error)

   QueryAndSort(c context.Context, searchTerm string, sortBy string) ([]Articles, error)

   QueryByStartDateAndEndDate(c context.Context, searchTerm string, startDate, endDate *time.Time) ([]Articles, error)

   QueryByStartDateAndSort(c context.Context, searchTerm string, startDate *time.Time, sortBy string) ([]Articles, error)

   QueryByEndDateAndSort(c context.Context, searchTerm string, endDate *time.Time, sortBy string) ([]Articles, error)

   QueryByStartDateAndEndDateAndSort(c context.Context, searchTerm string, startDate, endDate *time.Time, sortBy string) ([]Articles, error)

   ...

The number of functions multiplies exponentially by the number of config options

\...but at least we're not breaking any users


* That didn't work, let's use a config struct

   type QueryConfig struct {
      StartDate  *time.Time
      EndDate    *time.Time
      SortBy     string
   }

    Query(c context.Context, searchTerm string, qc *QueryConfig) ([]Articles, error) {
      if qc.StartDate == nil {
         qc.StartDate = &time.Now().UTC().AddDate(-1, 0, 0)
      }

      ...
   }

*Usage*

   Query(c, "gophers", &QueryConfig{
      StartDate: &time.Now().UTC().AddDate(-1, 0, 0),
      StartDate: &time.Now().UTC(),
      SortBy: "dateDescending",
   })


* Config 

*Pros:*

- Adding a new field isn't always a breaking change

- Docs are clearer, since each field can be commented individually

*Cons:*

- Adding a new field will break anyone expecting struct ordering (_idiots_)

- You can't always overwrite the zero value with the default

- Not obvious when default values are being used

- All configurable fields have to be public

- Query func bloats with each additional option



* Functional options to the rescue!

We'll actually still use a config struct, which you can choose to make public or private

   type QueryOption func(qc *queryConfig) error

   type queryConfig struct {
      startDate  time.Time
      endDate    time.Time
      sortBy     string
   }

The function signature should include required fields like `searchTerm`, and everything else is an option

   Query(c context.Context, searchTerm string, opts ...QueryOption) ([]Articles, error)

Now we're back to our original api usage

   Query(c, "gophers")

* Implementation details

It's super easy to see what the defaults are

   Query(c context.Context, searchTerm string, opts ...QueryOption) ([]Articles, error) {
      defaultOptions := &queryConfig{
         startDate: time.Now().UTC().AddDate(-1, 0, 0),
         endDate:   time.Now().UTC(),
         sortBy:    "dateDescending",
      }

      // apply each of the options individually in the order the user supplies them
      for _, opt := range opts {

         // each option func gets the queryConfig and can mutate it as needed
         if err := opt(defaultOptions); err != nil {
            return nil, err
         }
      }

      // make sure that there aren't invalid combinations (e.g. startDate after endDate)
      err := defaultOptions.validate()
      ...
   }

* Filter by beginning date (Non-breaking change)

   // WithStartDate restricts responses to results with publication dates
   // of the date specified or later.

   func WithStartDate(date time.Time) QueryOption {  

      return func(qc *queryConfig) error {
         qc.startDate = date
         return nil
      }

   }

*Usage*

   Query(c, "gophers",
      WithStartDate(time.Now().UTC().AddDate(-1, 0, 0)),
   )

* Filter by end date (Non-breaking change)

   // WithEndDate restricts responses to results with publication dates
   // of the date specified or earlier.

   func WithEndDate(date time.Time) QueryOption {  

      return func(qc *queryConfig) error {
         qc.endDate = date
         return nil
      }
      
   }


*Usage*

   Query(c, "gophers",
      WithEndDate(time.Now().UTC()),
   )

* Add sorting (Non-breaking change)

   // SortedByNewest sorts by the publish date descending

   func SortedByNewest() QueryOption {  

      return func(qc *queryConfig) error {
         qc.sortBy = "dateDescending"
         return nil
      }
      
   }

*Usage*

   Query(c, "gophers",
      SortedByNewest(),
   )

* Add limit (Non-breaking change)

   // WithLimit limits the results returned

   func WithLimit(limit int) QueryOption {  

      return func(qc *queryConfig) error {
         if limit < 0 {
            return errors.New("limit must be greater than 0")
         }
         qc.limit = limit
         return nil
      }
      
   }

*Usage*

   Query(c, "gophers",
      WithLimit(10),
   )

* Unlimited combinations

*Usage*

   Query(c, "gophers", 
      WithStartDate(time.Now().UTC().AddDate(-1, 0, 0)),
      SortedByNewest(),
   )

   Query(c, "gophers", 
      WithStartDate(time.Now().UTC().AddDate(-1, 0, 0)),
      WithEndDate(time.Now().UTC(),
      SortedByNewest(),
   )

   Query(c, "gophers", 
      WithMaxRetries(5), // retry 5 times
      WithPage(7),       // get page 7
      WithAuthor("Bob"), // filter to authors named Bob 
      WithTag("Go"),     // filter to articles tagged "Go"
      WithTagID(1234),   // filter to articles with tagID=1234
      BypassCache(),     // don't accept cached results
      WithClient(cl),    // make the request using a custom http client
   )

* Further consideration

- If you have incompatible options, error out

- The last options take precedence if there is conflict, but that should generally be obvious to the user

- You could also have the search term be an option to make this also work as a list call

- If you make the config public, users can write their own funcs

- We are migrating most of our internal apis to use functional options, currently > 12 services use it

* Comparison to the builder pattern

In many ways, this is similar to the builder pattern, where each option returns the original object, allowing for chained options

   NewQuery("gophers"). 
      WithStartDate(time.Now().UTC().AddDate(-1, 0, 0)).
      SortedByNewest().
      Do(c)

This has a few distinct differences:

- To chain, options have to return the query and can't error on invalid values

- The original object can be edited at any point, which is sometimes necessary, but opens up the possibility of race conditions


* Who is actively using functional options?

*gRPC*

  type DialOption func(*dialOptions)
    func WithAuthority(a string) DialOption
    func WithStatsHandler(h stats.Handler) DialOption

  type ServerOption func(*options)
    func Creds(c credentials.TransportCredentials) ServerOption
    func StreamInterceptor(i StreamServerInterceptor) ServerOption

.link https://godoc.org/google.golang.org/grpc

*golang.org/x/text/cases*

  type Option func(o options) options
    func HandleFinalSigma(enable bool) Option
    NoLower Option = noLower

.link https://godoc.org/golang.org/x/text/cases

* Inspiration and further reading

slides can be found at
.link http://talks.godoc.org/github.com/derekperkins/functional-options/talk.slide

example inspired by Giorgi Tkeshelashvili

.link http://gtkesh.com/functional-options-for-friendly-apis-nyt-articles-api-wrapper/

functional options popularized by Dave Cheney

.link https://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis

.link https://www.youtube.com/watch?v=24lFtGHWxAQ

originally suggested by the Commander himself

.link https://commandcenter.blogspot.com.au/2014/01/self-referential-functions-and-design.html