DEV Community: Mario Carrion

Microservices in Go: Events and Background jobs using Kafka

Mario Carrion — Fri, 03 Sep 2021 00:36:03 +0000

Post originally published at mariocarrion.com.

What is Kafka?

Kafka is an event streaming platform, it allows us to publish, subscribe, store and process events. An Event indicates something that happened, if we use our To Do Microservice as example, we could define events to indicate a TaskCreated or TaskUpdated when a Task is created or when a Task is updated, respectively.

How does Kafka work?

In Kafka there's a concept called Topic, Topics store events published by a Publisher; those Topics can be named for to differentiate between them and they can be Partitioned, what this means is that they could be separated into multiple Kafka brokers, or instances in charge of storing the topics, defining various partitions allows scaling Kafka to allow multiple publishers and consumers to write and read data.

When an event is published to a Topic it will be stored in order it was received, this allows the Consumers to read those events in the same order they were published:

Consumers use Group IDs to identify themselves when reading events that way multiple processes can consume the same topic in a way the events are still consumed in order:

Because of those Group IDs, multiple processes can read the same data at a different pace of speed without affecting other consumers:

Publisher implementation using a Repository

For communicating with Kafka we are going to use the official package confluentinc/confluent-kafka-go and similar to other Repositories we implemented previously a new package will be defined called kafka.

This package will implement the corresponding Task in charge of publishing the events that represent the actions executed when Tasks change to indicate creation, deletion and updates.

The code looks like this:

func (t *Task) Created(ctx context.Context, task internal.Task) error {
    return t.publish(ctx, "Task.Created", "tasks.event.created", task)
}

func (t *Task) Deleted(ctx context.Context, id string) error {
    return t.publish(ctx, "Task.Deleted", "tasks.event.deleted", internal.Task{ID: id})
}

func (t *Task) Updated(ctx context.Context, task internal.Task) error {
    return t.publish(ctx, "Task.Updated", "tasks.event.updated", task)
}

Those exported methods use an unexported method called publish that interacts directly with the Kafka Producer, the event to be sent will be encoded using encoding/json, the idea is to define a JSON payload that then our Consumers can use for determine what event to use, more in the section below covering Consumers:

func (t *Task) publish(ctx context.Context, spanName, routingKey string, e interface{}) error {
    // XXX: Excluding OpenTelemetry and error checking for simplicity
    var b bytes.Buffer

    evt := event{
        Type:  msgType,
        Value: task,
    }

    _ = json.NewEncoder(&b).Encode(evt)

    _ = t.producer.Produce(&kafka.Message{
        TopicPartition: kafka.TopicPartition{
            Topic:     &t.topicName,
            Partition: kafka.PartitionAny,
        },
        Value: b.Bytes(),
    }, nil)

    return nil
}

To connect this Kafka repository with the PostgreSQL repository we will update each method in service.Task to call the corresponding publish-related method, for example:

func (t *Task) Create(ctx context.Context, description string, priority internal.Priority, dates internal.Dates) (internal.Task, error) {
    // XXX: Excluding OpenTelemetry and error checking for simplicity
    task, _ := t.repo.Create(ctx, description, priority, dates)

    // XXX: Transactions will be revisited in future episodes.
    _ = t.msgBroker.Created(ctx, task) // XXX: Ignoring errors on purpose

    return task, nil
}

Refer to the original code to see how the other methods were updated to do something similar.

For consuming the events we will define a new program that will be using the same topic to read the data we published, and then it will update the Elasticsearch values using that repository.

Consumer implementation

Like I mentioned above the new program will consume the Kafka events and depending on the event type it will call the corresponding Elasticsearch method to reindex the values; this program also supports Graceful shutdown.

The program uses the Consumer to poll the values that represent the events to read, the simplified code looks like:

for run {
    msg, ok := s.kafka.Consumer.Poll(150).(*kafka.Message)
    if !ok {
        continue
    }

    var evt struct {
        Type  string
        Value internaldomain.Task
    }

    _ = json.NewDecoder(bytes.NewReader(msg.Value)).Decode(&evt)

    switch evt.Type {
    case "tasks.event.updated", "tasks.event.created":
        // call Elasticsearch to index record
    case "tasks.event.deleted":
        // call Elasticsearch to delete record
    }
}

When building your final program consider implementing a Server-like type, with the goal of separating the different received events into their corresponding types, that way your switch could be replaced with a map of functions pointing to the "handlers" of each type being consumed.

Conclusion

Kafka is a powerful platform for dealing with events, it could be used as a message broker to distribute information across multiple services but it also supports storing and replaying events as well as analysis of those events they are received.

Learning Go: Context package

Mario Carrion — Fri, 27 Aug 2021 02:38:48 +0000

Back in August 2016 Go 1.7 was released, it included among other things a new package called context. This package was originally implemented in golang.org/x/net/context but it was copied over to the standard library during this release.

This change made other standard library packages, like net, net/http and database/sql, to be updated to add support for the context package but without breaking existing APIs. That's why we see functions with similar name and arguments but with an extra context argument added as the first one, like database/sql.*DB 's Ping method:

func (db *DB) Ping() error
func (db *DB) PingContext(ctx context.Context) error

This decision was made because of the version one compatibility promise, however behind the scenes most of those methods use context but with default values, usually context.Background():

func (db *DB) Ping() error {
    return db.PingContext(context.Background())
}

One important thing to notice about those new methods is the fact that they defined a de-facto convention where if we need to use context.Context in our functions then it should be the first argument called ctx.

Let's dive into the context package.

What is in the `context` package?

The context package defines a type called Context that is used for deadlines, cancellation signals as well as a way to use request-scoped values.

context.Context is an interface type that defines four functions:

type Context interface {
    Deadline() (deadline time.Time, ok bool)
    Done() <-chan struct{}
    Err() error
    Value(key interface{}) interface{}
}

Depending on how we plan to use context.Context we may or may not use all the methods:

Deadline(): returns the time when the context should end, if no deadline is set then the returned bool value is false. This function is useful in cases where a context is received and we want to calculate if there's enough time to complete the work to be done.
Done(): returns a channel that is closed when the context ends, the way this channel is closed depends on how the context.Context was initialized, please refer to the docs for concrete details.
Err(): if there was an error then it returns a non-nil error when the returned channel in Done() was closed, either context.DeadlineExceeded or context.Canceled, otherwise nil.
Value(key interface{}): it's used to get a request-scoped value stored in the context, used in conjunction with context.WithValue.

It's most likely you're already using context in one way or another, for example if you're using database/sql or net/http; some projects rely heavily on context to achieve their goal, for example OpenTelemetry uses it intensively for instrumentation.

Deadlines

Deadlines define a way to indicate something has been completed using time, there are two ways to do that:

context.WithDeadline: uses a concrete time.Time to indicate when the context should finish, and
context.WithTimeout: uses a relative time.Duration to indicate when the context should finish.

If you refer to the source code you will notice that context.WithTimeout uses context.WithDeadline behind the scenes but adding the timeout to the current time to indicate the deadline:

func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc) {
    return WithDeadline(parent, time.Now().Add(timeout))
}

Both functions return a new context.Context as well as a context.CancelFunc function; this new context.Context is a copy of the parent one with deadline details attached to it and it's meant to be used as the argument for any subsequent calls that are supposed to be using a deadline.

The function context.CancelFunc should be called (usually via a defer) when the corresponding block of code using the new context.Context is completed, this is to propagate the cancellation to other functions using the context in case the deadline was reached.

For example:

ctx, cancel := context.WithTimeout(context.Background(), 1 * time.Millisecond)
defer cancel()

select {
case <-time.After(1 * time.Second):
    fmt.Println("overslept")
case <-ctx.Done():
    fmt.Println(ctx.Err()) // prints "context deadline exceeded"
}

The code above will always print context deadline exceeded because the value we indicated in the call context.WithTimeout is 1 millisecond, if we modify that value to be something higher than 1 second then it will print out overslept.

This is because the select is expecting for one of two channels to receive a message, either the one returned by time (via time.After()) or the one indicated in context (via ctx.Done()).

Cancellation signals

Cancellation signals define a way to indicate something has been completed by explicitly calling a CancelFunc function, there is one way to do it:

context.WithCancel: it returns a copy of the context and a CancelFunc to indicate when to cancel some work.

Similar to the Deadlines, for Cancellation signals a context.Context is returned as well as a CancelFunc; this function should be explicitly called to indicate when a returned context is canceled to propagate to other functions using the same context the work should stop.

The difference between context.WithCancel and context.WithDeadline/context.WithTimeout is the explicitness, so instead of defining a timeout the CancelFunc should be called explicitly. In all three cases we always need to call the returned CancelFunc to properly propagate the cancellation details to other functions using the same context.

For example:

ch := make(chan struct{})

run := func(ctx context.Context) {
    n := 1
    for {
        select {
        case <-ctx.Done(): // 2. "ctx" is cancelled, we close "ch"
            fmt.Println("exiting")
            close(ch)
            return // returning not to leak the goroutine
        default:
            time.Sleep(time.Millisecond * 300)
            fmt.Println(n)
            n++
        }
    }
}

ctx, cancel := context.WithCancel(context.Background())
go func() {
    time.Sleep(time.Second * 2)
    fmt.Println("goodbye")
    cancel() // 1. cancels "ctx"
}()

go run(ctx)

fmt.Println("waiting to cancel...")

<-ch // 3. "ch" is closed, we exit

fmt.Println("bye")

The code above is a bit more elaborated than the one used for Deadlines, the key part is the explicit cancel() call in the goroutine; that cancel() call is what in the end stops the run function that receives the cancelable context.

Request-scoped values

Request-scoped values define a way to set and get values that apply to concrete instances of context.Context, they are meant to be used only during a user request, for example during an HTTP request to pass down information to the subsequent internal calls, there is one way to do it:

context.WithValue: it returns a copy of the context that happens to include the value set.

For example:

ctx := context.WithValue(context.Background(), auth, "Bearer hi")

//-

bearer := ctx.Value(auth)
str, ok := bearer.(string)
if !ok {
    log.Fatalln("not a string")
}

fmt.Println("value:", str)

The code above uses both context.WithValue and context.Context.Value; context.WithValue returns a copy of the parent context with the associated value and key, then we can use that returned context and call its method Value to get the previously assigned value.

The complexity of context.WithValue is not about the implementation or usage but rather when to make those calls, recall the point of using this function is only for request-scoped values not things meant to live all the time during the execution of the program.

Some common examples include defining a value for JSON Web Tokens or extra headers, in both cases the values are meant to be passed around multiple requests to augment the subsequent requests.

Conclusion

Understanding how to use context.Context is important when dealing with instructions that require cancellation, for example HTTP requests, database commands or remote produce calls; not only because we need to define a sane value to indicate when to stop a running request to avoid waiting forever but also to identify when a remote call was canceled to properly react to that event.

context.Context provides a simpler way to deal with multiple goroutines to coordinate their work, to identify timeouts and to determine when those happen. Because instrumentation is an important part of any distributed system, knowing how those values are sent and defined between different calls is useful to understand the flow of our program.

Building Microservices in Go: Events and Background jobs using RabbitMQ

Mario Carrion — Fri, 20 Aug 2021 05:05:37 +0000

Originally published at mariocarrion.com

What is RabbitMQ?

RabbitMQ is a message-queueing software also known as a message broker or queue manager. It supports protocols such as AMQP, MQTT and STOMP, to name a few. RabbitMQ could be used for long-running tasks, for example background jobs, and for communication between different services.

How does RabbitMQ work?

The easiest analogy to describe RabbitMQ is that of a Post Office and the required steps involved, from beginning to end, to deliver a mail to the final destination. In real life those steps consist of dropping off the mail into a mailbox, then some processing behind the scenes to route that mail and finally a mail person brings that mail to the destination.

RabbitMQ works as a queue where Publishers can submit messages which then are eventually consumed by multiple Consumers; however the interesting part about RabbitMQ is the intermediary mechanism that sits between those publishers and consumers. This intermediary is called Exchange, this Exchange can be configured to define Bindings to allow those messages to be routed into different Queues which then the clients can listen to for consuming messages in different ways, to perhaps consume by a only concrete key or a wildcard.

Publisher implementation using a Repository

To interact with RabbitMQ we will use the package streadway/amqp and similar to other data stores we will be defining a Repository that will be interacting with the actual RabbitMQ publisher and will be called in the service type.

This repository type will be named rabbitmq.Task, it will contain an unexported field referencing a RabbitMQ channel and the corresponding methods required for emitting three events Created, Deleted and Updated:

func (t *Task) Created(ctx context.Context, task internal.Task) error {
    return t.publish(ctx, "Task.Created", "tasks.event.created", task)
}

func (t *Task) Deleted(ctx context.Context, id string) error {
    return t.publish(ctx, "Task.Deleted", "tasks.event.deleted", id)
}

func (t *Task) Updated(ctx context.Context, task internal.Task) error {
    return t.publish(ctx, "Task.Updated", "tasks.event.updated", task)
}

Those three methods will refer to an unexported method called publish, which is used for publishing the data, this data is the result encoding the message using the encoding/gob package, similar to the code used when we discussed Caching with Memcached:

func (t *Task) publish(ctx context.Context, spanName, routingKey string, e interface{}) error {
    // XXX: Excluding OpenTelemetry and error checking for simplicity
    var b bytes.Buffer

    _ = gob.NewEncoder(&b).Encode(e)

    _ = t.ch.Publish(
        "tasks",    // exchange
        routingKey, // routing key
        false,      // mandatory
        false,      // immediate
        amqp.Publishing{
            AppId:       "tasks-rest-server",
            ContentType: "application/x-encoding-gob",
            Body:        b.Bytes(),
            Timestamp:   time.Now(),
        })

    return nil
}

Next, in the service package the service.Task type is updated to receive an instance of that repository using an interface type, which then will be used it after the persistent datastore call is done, something like:

func (t *Task) Create(ctx context.Context, description string, priority internal.Priority, dates internal.Dates) (internal.Task, error) {
    // XXX: Excluding OpenTelemetry and error checking for simplicity
    task, _ := t.repo.Create(ctx, description, priority, dates)

    _ = t.msgBroker.Created(ctx, task)

    return task, nil
}

Please refer to the Delete call as well as the Update call for more details, in practice the code is similar to the one above.

Now, let's take a look at the subscriber implementation. For this example we will implement a new running process in charge of consuming that data.

Subscriber implementation

This new process will consume those RabbitMQ events to properly index the Task records, changing the way we were using Elasticsearch originally, it will also support Graceful shutdown like we previously covered.

The code for listening, at the moment, is a slightly long method, the important part would be the actual Go channel returned by RabbitMQ, this code does something like the following to receive all events:

// XXX: Excluding some things for simplicity, please refer to the original code
for msg := range msgs {
    switch msg.RoutingKey {
    case "tasks.event.updated", "tasks.event.created":
        // decode received Task event
        // call Elasticsearch to index record
    case "tasks.event.deleted":
        // decode received Task event
        // call Elasticsearch to delete record
    }
    // acknowledege received event
}

In a real-life implementation you should consider implementing a Server type able to handle different events, perhaps similar to the way net/http.Server works and maybe define something similar to a Muxer to allow listening to multiple events with their corresponding encoding/decoding logic.

Conclusion

RabbitMQ is commonly known as a distributed queue but it can also be used as a message broker to communicate multiple services, is a powerful tool that thanks to the available configuration options could serve to deliver messages to multiple clients at scale.

Why you should use/learn Go as hiring manager/individual contributor.

Mario Carrion — Fri, 13 Aug 2021 10:58:56 +0000

When choosing a technology to build a software project the final decision will depend on the experience the team has and the risk they are allowed to take, using Go may not be the first choice because of the uncertainty the language can bring. This uncertainty can be measured by multiple known unknowns like support (either commercial or community-based), availability of libraries and packages, documentation and examples, pool of available engineers or language complexity, to mention a few.

Go is relatively a new programming language, it is 11 years old (to date) and it is still evolving like any other language but in a slower pace compared to other ones, this is in my opinion because the promised version one compatibility at source level, this longevity is also another factor companies take into consideration during the decision making.

In this post I will tackle different concerns related to whether using Go or not, those concerns will be from two point of views: Hiring Manager and Individual Contributor.

Hiring Manager

Hiring Manager is a broad term, for this post I define it as the Person in charge of making the decisions of what Engineer to hire, and the expertise this person should have, for building a piece of software; this Person is someone involved with the project that is part of that piece of software, most of the times a Lead Engineer that is trying to hire someone to join the project.

This project could be new or current, for this specific post I'm assuming it's new where Go is considered as one of technologies to use.

What are the cons?

Difficult to find talent

This is a valid concern, choosing a language that nobody knows or nobody is willing to learn delays the project and makes implementing this new piece of software harder than initially planned. Please continue reading there's more about this to explore regarding training and easiness to learn.

Training may be needed

If people don't know the language then teaching them is going to be required, this is a con for sure but thanks to the language learning it may not take too much time or effort, however is something to consider and something that could delay the progress of the project.

Salary or Compensation

If an Engineer with Go experience is found, it's most likely the compensation will be a bit higher because of the rarity of this combination, specially for Senior Engineers the compensation could be a big problem for companies not willing to make a good offer for this kind of experience.

What are the pros?

Easy to learn

Go is a simple, yet powerful, language. It does not define a lot of keywords or different ways to do things, sure there are few gotchas that could creep in when a novice engineer starts learning the language but in my opinion it is easy to learn and it tries its best to be as explicit as possible.

Vendor-supported

Part of choosing a technology, like programming language, consists of having options to use with other technologies, for example cloud providers like Google Cloud, Amazon Web Services and Azure provide SDKs in Go, the support may vary depending on the service but the option to use Go is there; popular datastores like MySQL, PostgreSQL, Redis, Kafka and Elasticsearch have packages available either created by the company providing commercial support or the community, so that's another thing to consider; not to mention the possibility to use any of the three most popular Operating Systems for development because it supports Microsoft Windows, Linux and MacOS.

Individual Contributor

Individual Contributor is the person not in charge of hiring concerns, this person does get involved with the decisions being made regarding the technologies to use but as an Individual Contributor this person is much more familiar with the internals of the codebase and the project being built. In the context of this post I also consider Individual Contributor someone willing to spend time learning the Go language, considering the investments to make and the possible return of effort if the decision to use the language is made.

What are the cons?

Backend-friendly

If you're interested in using a programming language that can be used for both the Frontend and Backend then learning Go may not be ideal. There are ways to write code in Go that can be displayed in a browser, for example using WebAssembly but this is a new technology that is not widely adopted yet.

Literature

Depending on your experience and the problem you're trying to solve perhaps the documentation available is not enough, and popular resources like Stackoverflow (and its Go Collective) could not provide the right answer.

Although to date there is a lot of content available covering most of the things related to Go, in some specific cases there's a learning curve that you will have to go through before being able to reach to a solution to some problems, some common examples can be things like Project Layout, Accessing Datastores or Frameworks.

What are the pros?

Easy to learn

Easy is relative, if Go is your first programming language then it is going to take you longer to learn it compared to someone with programming experience, however because of the way the language was designed, the amount of keywords and ways to do things is finite even if this is your first language it shouldn't take you that long when using the right literature.

Friendly Community

There are different ways to reach out the Go community, like GophersSlack or Reddit; there's also the yearly GopherCon conference and depending on where you live maybe there's a MeetUp group or a local conference as well.

Whatever way you prefer to interact with the community you can rest assured there's always someone willing to help you and answer any questions.

Backend-friendly

Also a con but depending on your career goals it could be a pro, this is because Go is a great language for Backend-related projects like CLI tools and Web Services.

Conclusion

Go is one of my favorite programming languages, I like it because it provides features I consider necessary like creating a single binary as the final artifact, a garbage collector and static typing; those are not Go-only features by any means but in Go those are provided without any extra baggage like in other languages.

Regarding support and packages available, the amount of them nowadays is vast compared to few years ago, and because of that there's a small risk when choosing Go.

Go is not perfect, dependency management and error handling are some of the most common complaints I hear all the time; I personally like the way errors are implemented but I do see some improvements needed when dealing with dependencies and versioning.

In the end I think Go is worth learning and giving a try, it could be a differentiator when building Microservices or CLI tools because of the features already included in the standard library as well as the way you could distribute your program as a single binary.

Building Microservices in Go: Searching with Elasticsearch

Mario Carrion — Thu, 05 Aug 2021 17:21:25 +0000

What is Elasticsearch?

Source (emphasis mine):

Elasticsearch is the central component of the Elastic Stack, commonly known as ELK, this stack consists of the following services:

E: Elasticsearch,
L: Logstash, and
K: Kibana.

Elasticsearch is a well known tool, already supported by all three big cloud providers:

Amazon Web Services has Managed Elasticsearch
Google Cloud Provider has Elastic Cloud
Microsoft Azure has Elastic Cloud

Using Elasticsearch in Go

There are two two popular packages for interacting with Elasticsearch in Go:

github.com/elastic/go-elasticsearch: the official Go package supported by Elastic, and
github.com/olivere/elastic: unofficial package, well-known in the community.

Which one should we choose?

Both of those packages are well supported and production ready, however between the two of them I'm leaning towards using elastic/go-elasticsearch instead of olivere/elastic this is because of the comment made by Oliver Eilhard (the author of olivere/elastic) on Github where he mentions that perhaps a v8 of that package will not be available, that could be an issue if you're planning to upgrade to Elasticsearch Version 8 when that version is available.

To be fair, to date, the work done by Oliver Eilhard simplifies a lot of the things needed when interacting with the Elasticsearch API which otherwise would have to be explicitly indicated when using the official one, this is because the way olivere/elastic/v7 is implemented it literally covers all the possible options available in the official API and because it's implemented using a fluent-like API its usage and default values are predefined from the beginning.

Using `elastic/go-elasticsearch`

For implementing the Elasticsearch datastore we are going to follow the Repository Pattern to update our "To Do Microservice". We will define a new elasticsearch package with a new type, it will include the corresponding logic needed for indexing, searching as well as deleting records. This type will be called as part of the already existing service.Task, finally we will expose this feature to our clients via a new HTTP API for searching tasks.

The code in practice, for indexing, looks more or less like this:

func (t *Task) Index(ctx context.Context, task internal.Task) error {
    // XXX: Excluding OpenTelemetry and error checking for simplicity

    body := indexedTask{
        ID:          task.ID,
        Description: task.Description,
        Priority:    task.Priority,
        IsDone:      task.IsDone,
        DateStart:   task.Dates.Start.UnixNano(),
        DateDue:     task.Dates.Due.UnixNano(),
    }

    var buf bytes.Buffer

    _ = json.NewEncoder(&buf).Encode(body) // XXX: error omitted

    req := esv7api.IndexRequest{
        Index:      t.index,
        Body:       &buf,
        DocumentID: task.ID,
        Refresh:    "true",
    }

    _ = req.Do(ctx, t.client) // XXX: error omitted
    defer resp.Body.Close()

    io.Copy(ioutil.Discard, resp.Body)

    return nil
}

And for searching it would look similar to:

func (t *Task) Search(ctx context.Context, description *string, priority *internal.Priority, isDone *bool) ([]internal.Task, error) {
    // XXX: Excluding OpenTelemetry and error checking for simplicity

    if description == nil && priority == nil && isDone == nil {
        return nil, nil
    }

    should := make([]interface{}, 0, 3)

    if description != nil {
        should = append(should, map[string]interface{}{
            "match": map[string]interface{}{
                "description": *description,
            },
        })
    }

    if priority != nil {
        should = append(should, map[string]interface{}{
            "match": map[string]interface{}{
                "priority": *priority,
            },
        })
    }

    if isDone != nil {
        should = append(should, map[string]interface{}{
            "match": map[string]interface{}{
                "is_done": *isDone,
            },
        })
    }

    var query map[string]interface{}

    if len(should) > 1 {
        query = map[string]interface{}{
            "query": map[string]interface{}{
                "bool": map[string]interface{}{
                    "should": should,
                },
            },
        }
    } else {
        query = map[string]interface{}{
            "query": should[0],
        }
    }

    var buf bytes.Buffer

    _ = json.NewEncoder(&buf).Encode(query)

    req := esv7api.SearchRequest{
        Index: []string{t.index},
        Body:  &buf,
    }

    resp, _ = req.Do(ctx, t.client) // XXX: error omitted
    defer resp.Body.Close()

    var hits struct {
        Hits struct {
            Hits []struct {
                Source indexedTask `json:"_source"`
            } `json:"hits"`
        } `json:"hits"`
    }

    _ = json.NewDecoder(resp.Body).Decode(&hits) // XXX: error omitted

    res := make([]internal.Task, len(hits.Hits.Hits))

    for i, hit := range hits.Hits.Hits {
        res[i].ID = hit.Source.ID
        res[i].Description = hit.Source.Description
        res[i].Priority = internal.Priority(hit.Source.Priority)
        res[i].Dates.Due = time.Unix(0, hit.Source.DateDue).UTC()
        res[i].Dates.Start = time.Unix(0, hit.Source.DateStart).UTC()
    }

    return res, nil
}

In both cases please refer to the original implementation for concrete details, like I mentioned before there's also a Delete method meant to be called when deleting previously indexed Tasks.

To connect those calls we need to update our service type to explicitly call the Search Store to execute the new actions we already defined; in future posts I will cover how to do this using events instead of explicitly calling stores directly in the service implementation.

For example the service.Task type will be doing something like the following in Create:

// Create stores a new record.
func (t *Task) Create(ctx context.Context, description string, priority internal.Priority, dates internal.Dates) (internal.Task, error) {
    // XXX: Excluding OpenTelemetry and error checking for simplicity

    task, _ := t.repo.Create(ctx, description, priority, dates)

    _ = t.search.Index(ctx, task) // XXX: New Search call to index and store records

    return task, nil
}

Similar calls are going to be added to index and a new method for searching records:

func (t *Task) By(ctx context.Context, description *string, priority *internal.Priority, isDone *bool) ([]internal.Task, error) {
  // XXX: Excluding OpenTelemetry and error checking for simplicity

    res, _ := t.search.Search(ctx, description, priority, isDone) // XXX: error omitted

    return res, nil
}

Similar to the other datastore used by this service.Task we also use Dependency Injection to refer to the concrete initialized elasticsearch.Task store.

Conclusion

Elasticsearch is a powerful tool that allows searching records in multiple different ways, it scales horizontally and supports multiple ways to index and search values, for example when using text-based fields it could transform numbers into words to allow searching both the actual literal number and the humanized way to express the value.

Similarly it allows scoring fields to sort them depending on how many matches they provide giving you the flexibility to display those first by popularity, as well as other popular features like fuzzy searching that match records related to the searched terms.

One thing to keep in mind when using Elasticsearch is that sometimes major version upgrades bring behavior-like breaking changes even if the API is still the same.

Elasticsearch includes more than what I mentioned above it's a really powerful tool that could also be used for analytics, it could be overwhelming to use for sure but it's a tool that should not be ignored.

Building Microservices in Go: Graceful Shutdown

Mario Carrion — Thu, 29 Jul 2021 21:23:02 +0000

When building any long-term running process, like a webserver or a program importing data, we should consider providing a way to gracefully shut it down, the idea behind this is to provide a way to exit the process cleanly, to clean up resources and to properly cancel that said running process.

The steps to support Graceful Shutdown in Go consist of two steps:

Listen for OS signals, and
Handle those signals.

In Go those signals are provided by the os/signal package. Starting with Go 1.16 the way I like to implement Graceful Shutdown is by using os/signal.NotifyContext, this function provides an idiomatic way to propagate cancellation when using goroutines, which is usually the case when dealing with long-term running processes.

Keep in mind that depending on how our main package is implemented you may need to refactor it, having the main function to reach the following objectives:

Call a Parse function, if needed, like flag.Parse(), and
Call a run-like function.

The run function is the one orchestrating all the different types, initializing everything, connecting all the dots and perhaps using explicit Dependency Injection, and more importantly it may run a few goroutines to implement the call to signal.NotifyContext that in the end is going to handle the logic for implementing Graceful Shutdown.

Let's look at some concrete examples.

Using `signal.NotifyContext`

Starting in Go 1.16 signal.NotifyContext is the way I like to recommend when handling signals, this replaces the previous way where a channel was required.

For example having the same main():

func main() {
    errC := run()
    if err := <-errC; err != nil {
        fmt.Println("error", err)
    }
    fmt.Println("exiting...")
}

When using signal.Notify:

func run() <-chan error {
    errC := make(chan error, 1)

    sc := make(chan os.Signal, 1)

    signal.Notify(sc,
        os.Interrupt,
        syscall.SIGTERM,
        syscall.SIGQUIT)

    go func() {
        defer close(errC)

        fmt.Println("waiting for signal...")

        <-sc

        fmt.Println("signal received")
    }()

    return errC
}

And when using signal.NotifyContext:

func run() <-chan error {
    errC := make(chan error, 1)

    ctx, stop := signal.NotifyContext(context.Background(),
        os.Interrupt,
        syscall.SIGTERM,
        syscall.SIGQUIT)

    go func() {
        defer func() {
            stop()
            close(errC)
        }()

        fmt.Println("waiting for signal...")

        <-ctx.Done()

        fmt.Println("signal received")
    }()

    return errC
}

In practice both of them work achieve the same goal because both of them are meant to listen to signals, however the biggest difference is that signal.NotifyContext provides a context ctx that could be used for creating more complex propagation rules (like timeouts for example) that we can use to cancel other goroutines, instead of doing more work manually.

Implementing Graceful Shutdown in HTTP Servers

Included in the standard library, in net/http, Go includes its own HTTP Server in net/http.Server, this server defines a method called Shutdown meant to be called when the server is supposed to exit and it shutdowns the server gracefully.

If we use the snippet we defined above we can write our code to handle Graceful Shutdown for HTTP servers in the following way:

    // ... other code initializing things used by this HTTP server

    go func() {
        <-ctx.Done()

        fmt.Println("Shutdown signal received")

        ctxTimeout, cancel := context.WithTimeout(context.Background(), 5*time.Second)

        defer func() {
            stop()
            cancel()
            close(errC)
        }()

        srv.SetKeepAlivesEnabled(false)

        if err := srv.Shutdown(ctxTimeout); err != nil {
            errC <- err
        }

        fmt.Println("Shutdown completed")
    }()

    go func() {
        fmt.Println("Listening and serving")

        // "ListenAndServe always returns a non-nil error. After Shutdown or Close, the returned error is
        // ErrServerClosed."
        if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
            errC <- err
        }
    }()

    return errC

Conclusion

The goal of implementing Graceful Shutdowns is to allow defining some clean-up steps when dealing with a long-running process, in cases where perhaps we need to commit some database transactions, remove some used files or maybe trigger an event to indicate some other process should take over the subsequent events.

Building Microservices in Go: Containerization using Docker

Mario Carrion — Thu, 22 Jul 2021 21:34:49 +0000

In the past I covered Docker from different point of views, including creating small docker images, building private Go packages with GitlabCI as well as using it for integration testing.

This time I will discuss briefly a few cloud providers (and their services) supporting Docker images, the most recent changes Docker added a few years ago to enable multi-stage builds for building small images and how to use docker-compose for local development.

What is Docker?

From the official site:

Those containers are created after instantiating Docker Images, those images need Docker Registries for distributing those same images to different users, the most popular Docker Registries at the moment for hosting docker images include:

You can still have the option to run a registry on-premise if needed. For orchestrating those Docker Containers some of the most popular cloud-based provider services available at the moment are:

How to use multi-stage builds?

The key parts to use multi-stage builds are to name the image, or images, to use and then call those images in subsequent calls. Please refer to the original Dockerfile for more details.

For example:

FROM golang:1.16.2-alpine3.13 AS builder

# ... commands are called here ...

FROM alpine:3.13 AS certificates

# ... more commands are called here ...

FROM scratch

# We refer to the previous stages, to copy the artifacts we created in previous stages.

COPY --from=certificates /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt

COPY --from=builder /build/rest-server ./bin/rest-server

In this case we are using two images in three steps:

builder: it is used for building the binaries,
certificates: it is used for installing the required certificates, and
Last one, we are copying the files we need from the other two to finally create the image.

With that we can generate the smallest docker image we can actually have for our use case.

Using Docker Compose for local development

When developing locally we could either run the needed services manually or use something like docker-compose, this really depends on your personal preference, I like running the docker containers manually instead of depending on docker-compose, the reason for this is that, to date, there's no way to really depend on a service and wait until that one is completely initialized without adding a third-party program to handle that.

To rephrase it, some containers take longer to initialize and if there is a service depending on them it will start first then and it will fail because the ones that it depends on are still not ready.

To handle that limitation when using docker-compose we can re-run those containers after the ones that fail, using our To-Do Microservice docker-compose.yml file for a concrete example, we do:

Execute docker-compose up, this step will start all the required services with their corresponding containers, we expect the api service to fail because the postgres service takes longer to start.
If we run docker-compose up api only, then the api service will start successfully but we won't be able to interact with it because the database schema is not up to date, for that we need to run the database migrations.
Running docker-compose run api migrate -path /api/migrations/ -database postgres://user:password@postgres:5432/dbname?sslmode=disable up will complete the step of migrating the database to the new version and with that we finally have everything working correctly.

Conclusion

Using containers is not something new but Docker popularized and made it easier for everybody to create and use those containers, over the years cloud service providers, like Amazon and Google Cloud, started supporting those artifacts and integrated them into their services, they even implemented their own versions of popular orchestration tools for containers, like Amazon Elastic Container Service (ECS) and Google Kubernetes Engine (GKE).

Using Docker and containers is not a requirement for Microservices but using that together with orchestration tools could result in a good usage of the infrastucture resources being used to make those said Microservices live.

Building Microservices in Go: OpenTelemetry

Mario Carrion — Thu, 15 Jul 2021 17:24:19 +0000

Original link

What is OpenTelemetry?

Source (emphasis mine):

In a way OpenTelemetry was the indirect result of observability, where the need to monitor multiple services written in different technologies made harder to collect and aggregate observability data.

OpenTelemetry does not provide concrete observability backends but rather a standard way to configure, emit, collect, process and export telemetry data; there are commercially-supported options for those backends, like NewRelic and Lightstep, as well as some Open Source projects that can be used with it, for this post I'm covering specifically:

Prometheus for collecting metrics, and
Jaeger for collecting traces

OpenTelemetry support for logs in Go, to date, is not implemented yet, however I'm still showing you how to log data using Uber's zap.

Using OpenTelemetry in Go

At the moment the following is the OpenTelemetry status regarding the support in Go:

Tracing Beta
Metrics Alpha
Logging Not yet implemented

The official documentation describes the steps required for adding OpenTelemetry support to Go programs, although the implementation has not reached a major official release we can still use it in production. There's also a registry that lists different packages for Go that implement instrumentation or tracing.

Metrics

For collecting metrics Prometheus will be used. To define this exporter the official OpenTelemetry-Go Prometheus Exporter is used as following:

promExporter, _ := prometheus.NewExportPipeline(prometheus.Config{}) // XXX: error omitted for brevity
global.SetMeterProvider(promExporter.MeterProvider())

This exporter implements http.Handler, so we can define it as another endpoint part of our HTTP Server, which then Prometheus will be using for polling metric values:

r := mux.NewRouter()
r.Handle("/metrics", promExporter)

One important thing about this is that because Prometheus is polling values from our service we must indicate what address and port to use, because we are using docker there's a configuration file that includes:

scrape_configs:
- job_name: to-do-api
  scrape_interval: 5s
  static_configs:
  - targets: ['host.docker.internal:9234']

Visiting http://localhost:9090/ should display a user interface like the following after typing a metric and selecting it:

Tracing

For collecting metrics Jaeger will be used. Compared to the Metrics one, defining this exporter is a slightly more elaborated. It requires the following:

jaegerEndpoint, _ := conf.Get("JAEGER_ENDPOINT")

jaegerExporter, _ := jaeger.NewRawExporter(
    jaeger.WithCollectorEndpoint(jaegerEndpoint),
    jaeger.WithSDKOptions(sdktrace.WithSampler(sdktrace.AlwaysSample())),
    jaeger.WithProcessFromEnv(),
) // XXX: error omitted for brevity

tp := sdktrace.NewTracerProvider(
    sdktrace.WithSampler(sdktrace.AlwaysSample()),
    sdktrace.WithSyncer(jaegerExporter),
)

otel.SetTracerProvider(tp)
otel.SetTextMapPropagator(propagation.NewCompositeTextMapPropagator(propagation.TraceContext{}, propagation.Baggage{}))

Defining that is the first step for having complete tracing support in our program, next we have to define Spans, either manually or automatically depending on the existing wrapper we are planning to use for whatever we want to trace; in our case we are doing it manually.

For example in the postgresql package each method of each type defines instructions like the following:

ctx, span := trace.SpanFromContext(ctx).Tracer().Start(ctx, "<name>")
 // If needed: N calls to "span.SetAttributes(...)"
defer span.End()

For example in postgres.Task.Create, we have:

ctx, span := trace.SpanFromContext(ctx).Tracer().Start(ctx, "Task.Create")
span.SetAttributes(attribute.String("db.system", "postgresql"))
defer span.End()

The OpenTelemetry specification defines a few conventions regarding attribute names and supported values, so the attribute db.system we used above is part of the Database conventions; in some cases the go.opentelemetry.io/otel/semconv package defines constants we can use, but this is not always the case so keep an eye out.

Similarly the equivalent service.Task.Create method does the following:

ctx, span := trace.SpanFromContext(ctx).Tracer().Start(ctx, "Task.Create")
defer span.End()

This is so we can record the call from each layer to measure how much time it took to complete as well as any possible errors that happen. Visiting http://localhost:16686/search should display a user interface like the following:

After clicking "Find Traces" we should see something like:

Where each Span is a layer that describes the interactions taken by the whole call. The interesting thing about OpenTelemetry and spans is that if there are interactions that include other OpenTelemetry-enabled calls, we could join them to see the full interaction between all of them.

Logs

Although OpenTelemetry does not support logs in Go yet, logging certain messages should be considered when Building Microservices; the approach I like to recommend is to define a logger instance and then when needed pass it around as an argument when initializating concrete types, the package we are going to be using is uber-go/zap.

Our code implements a middleware to log all requests:

logger, _ := zap.NewProduction()
defer logger.Sync()

middleware := func(h http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        logger.Info(r.Method,
            zap.Time("time", time.Now()),
            zap.String("url", r.URL.String()),
        )

        h.ServeHTTP(w, r)
    })
}

Which then we use to wrap the muxer and therefore all the handlers:

srv := &http.Server{
    Handler: middleware(r),
    // ... other fields ...
}

Conclusion

OpenTelemetry, for Go specifically, is a work in progress, it's definitely a good idea but it is hard to keep your own code up to date with the minor releases, because those happen to break API from time to time. For long running projects I'd recommend to wait until a major version is released, otherwise finding a non-OpenTelemetry option may make more sense.

I will continue monitoring the progress of this project in future posts, until then I will talk to you later.

Building Microservices in Go: REST APIs: Implementing and Dealing with errors

Mario Carrion — Thu, 08 Jul 2021 20:12:00 +0000

When building any software, specifically Microservices, there's something we should always be aware of, something that is going to happen no matter what: errors.

Failures are always something we have to consider when building new software products, it's part of the territory and there's no way around it, specially when building distributed systems.

The problem is not failing but rather the lack of planning regarding monitoring and reacting to those failures.

Introduction to errors

Errors in Go are simple in a sense any type implementing the error interface is considered an error, the idea with errors is to detect them, do something with them and if needed bubble them up so the callers can also do something with them:

if err := function(); err != nil {
  // something happens
  return err
}

In Go 1.13 a few extra methods were added to the errors package to handle identifying and working errors in a better way, specifically:

errors.Is

Instead of comparing a sentinel error using the == operator we can use something like:

if err == io.ErrUnexpectedEOF // Before
if errors.Is(err, io.ErrUnexpectedEOF) // After

errors.As

Instead of explicitly do the type assertion we can use this function:

if e, ok := err.(*os.PathError); ok // Before

var e *os.PathError // After
if errors.As(err, &e)

New fmt verb %w and errors.Unwrap, with the idea of decorating errors with more details but still keeping the original error intact. For example:

fmt.Errorf("something failed: %w", err)

This errors.Unwrap function is going to make more sense when looking at the code implemented below.

Implementing a custom error type with state

Our code implements an error type called internal.Error, this new type includes state, the idea of this state is to define an Error Code that we can use to properly render different responses on our HTTP layer. Those different responses are going to be determined by the code that is included in the error.

It looks like this:

// Error represents an error that could be wrapping another error, it includes a code for determining
// what triggered the error.
type Error struct {
    orig error
    msg  string
    code ErrorCode
}

And the supported error codes:

const (
    ErrorCodeUnknown ErrorCode = iota
    ErrorCodeNotFound
    ErrorCodeInvalidArgument
)

With those types we can define a few extra functions to help us wrap the original errors, for example our PostgreSQL repository, uses WrapErrorf to wrap the error and add extra details regarding what happend:

return internal.Task{}, internal.WrapErrorf(err, internal.ErrorCodeUnknown, "insert task")

Then if this error happens, the HTTP layer can react to it and render a corresponding response with the right status code:

func renderErrorResponse(w http.ResponseWriter, msg string, err error) {
    resp := ErrorResponse{Error: msg}
    status := http.StatusInternalServerError

    var ierr *internal.Error
    if !errors.As(err, &ierr) {
        resp.Error = "internal error"
    } else {
        switch ierr.Code() {
        case internal.ErrorCodeNotFound:
            status = http.StatusNotFound
        case internal.ErrorCodeInvalidArgument:
            status = http.StatusBadRequest
        }
    }

    renderResponse(w, resp, status)
}

Conclusion

The idea of defining your own errors is to consolidate different ways to handle them, adding state to them allows us to react differently; in our case it would be about rendering different responses depending on the code; but maybe in your use case it could main triggering different alerts or sending messages to different services.

Building Microservices in Go: REST APIs: Putting it all together

Mario Carrion — Sat, 03 Jul 2021 17:00:48 +0000

Putting it All Together

The last five posts covered all steps I consider necessary for building the barebones of a REST API, it's not a complete list for sure, it's missing things like deployment, infrastructure and other important details we must consider before making the API live, like scalability, reliability, instrumentation, monitoring and logging, but I will cover those in detail in future posts.

The following are the concrete decisions I like to follow when building brand new API from scratch:

Types to match HTTP resources

This was covered when I talked about HTTP Handlers where I mentioned implementing a type to take care of everything related to Tasks. I like following this guideline because the Go types can easily be categorized and organized accordingly to the HTTP resources they represent.

Custom Go Types to describe JSON payloads

Implementing Custom JSON Types is extra work for sure, but I believe making the user experience better for our costumers always matter, sure it's more work for the team in charge of building the APIs but defining more humanized types allows defining much more clearer values for the fields used in the payloads.

Considering JSON is the de facto format used for HTTP-based APIs it's important we take advantage of the verbosity we have and be as explicit as we can. The common use case would be to define custom Go types representing enum values in JSON.

Document your APIs

OpenAPI is a great way to create a standardized documentation, we can share it with our costumers as well as with the team in charge of implementing the actual APIs in code.

The process I described in the post works but I like following a different approach to make sure the different services depending on that documentation don't have circular relationships.

To do that the actual document is generated outside of the project implementing it, and the project meant to implement the code can enforce the rules defined by the document as well as reusing the code that was could be generated from it.

Conclusion

Finally, regarding the most difficult topic IMO: versioning, I like keeping it simple and use path-based APIs; technically in the end using any of the possible options is easy to do thanks to existing gateways that could route requests to different implementations as needed.

In future posts I will cover more things to consider when Building Microservices in Go, until then I will talk to you later.

Building Microservices in Go: REST APIs - Versioning

Mario Carrion — Sun, 27 Jun 2021 16:44:51 +0000

What is versioning in software?

Versioning is the idea of identifying a concrete piece of software based on a value, where this value could used to reference the contract being followed by both the provider of that software as well as the user of that software.

One example, in the context of REST APIs, would be to identify the fields and types used in the payload of the same resource over time.

There are multiple ways to create this identity, from uniquely generated values to sequentially incremented numbers as well as values using release dates. In some cases special rules could be applied to those identifiers, like using odd-numbers to indicate unstable releases.

Choosing a versioning technique with clearly defined rules is important for both the team in charge of building the product as well as your users to understand how, when and if a version update is needed, this is where Semantic Versioning comes in.

What is Semantic Versioning?

Semantic Versioning is a collection of rules and requirements that determine how version numbers are assigned and incremented. Go, for example, uses it for managing dependencies as part of Go modules.

The way it works is by defining a versioning format consisting of three numbers with specific names and rules: X.Y.Z, where:

X: represents a major value,
Y: represents a minor value, and
Z: represents a patch value,

Each value indicates how compatible the version is compared to another one, all of this is better explained by the Semantic Versioning 2.0 Summary (emphasis mine):

How can we implement versioning for REST APIs?

There is no official recommendation, but different companies in the software industry like to take any of the following approaches, all of them with specific tradeoffs:

Using a path
Defining subdomains
Receiving query arguments
Accepting headers

Versioning using a path

Differentiate versions by a parent path, which identifies (most of the times) the major version, for example:

GET https://todo.app/**v1**/tasks/{taskId}
GET https://todo.app/**v2**/tasks/{taskId}

A real life example of this is the Blogger API, which at the moment defines two supported APIs with similar resources:

Version 2 and
Version 3

For example the Blogs: Get API:

Version 2: GET https://www.googleapis.com/blogger/v2/blogs/{blogId} and
Version 3: GET https://www.googleapis.com/blogger/v3/blogs/{blogId}

Implementation details:

In Go: each version defines a concrete handler that happens to be using specific paths, requests and response types.
Not Go: two different microservices using a gateway that uses the path to redirect traffic to specific versions.
OpenAPI/Swagger: can be used.

Versioning using subdomains

Differentiate versions by subdomain, which identifies (most of the times) the major version, for example:

GET https://**v1**.todo.app/tasks/{taskId}
GET https://**v2**.todo.app/tasks/{taskId}

Implementation details:

They could literally be two different microservices, totally independent of each other.
OpenAPI/Swagger: can be used.

Versioning using query arguments

Differentiate versions by query arguments, with the possibility to indicate exactly the version to use, for example:

GET https://todo.app/tasks/{taskId}?**v=1**
GET https://todo.app/tasks/{taskId}?**v=2**

For example Microsoft Azure DevOps Services uses this approach where a way to specify the version would be using something like:

GET https://dev.azure.com/{organization}/_apis/{area}/{resource}?api-version=1.0

Implementation details:

When using different technologies: a gateway could be used,
When using the same technologies: complicated to maintain because both may be using the same underlying handler, either a switch-like style or map-based functions; or literally implement a new microservice and use a gateway,
OpenAPI/Swagger: hard to define requests and schemas, but possible, Microsoft Azure Cognitive Search: api-version does that.

Versioning using headers

Differentiate versions by values in the HTTP headers:

Using a custom Header:

GET -H **"Version: <VERSION>"** https://todo.app/tasks/{taskId}, or

Using Content Negotiation, for example Github uses a vendor prefix to do so:

GET -H **"Accept: application/vnd.todo.<VERSION>+json"** https://todo.app/tasks/{taskId}

Implementation details:

When using different technologies: a gateway could be used,
When using the same technologies: complicated to maintain because both may be using the same underlying handler, either a switch-like style or map-based functions; or literally implement a new microservice and use a gateway,
OpenAPI/Swagger: hard to define requests and schemas, but possible, Github does that.

Conclusion

So what is the best option? The usual answer: "It depends".

In the end I believe the customer experience matters the most and perhaps taking the simplest approach, like using subdomains or paths, makes adopting your API easier for your customers increasing your market-share.

Besides selecting a way to version HTTP REST APIs, the important thing to know is how and when to introduce breaking changes, the approach I like taking is the following:

Before adding a new major version:
- Delay v1 as much as possible, literally stay with v0 "forever", or at least make it clear to your customers breaking changes may be expected.
- Try to make your changes additive only and deprecate old ones.
While dealing with multiple versions. Consider a hybrid, for example Paths:
- v1: GET https://todo.app/v1/tasks/{taskId}
- v1: deprecated PUT https://todo.app/v1/tasks/{taskId}
- v2: PUT https://todo.app/v2/tasks/{taskId}
After:
- Encourage users to upgrade to new version by clearly indicating new features and capabilities,
- Provide a way to automatically upgrade, and
- Give a concrete deadline, plan deprecating older versions, if you can; in some cases building a bridge API to convert from one to another could be needed.

Building Microservices in Go: REST APIs - OpenAPI 3 and Swagger UI

Mario Carrion — Sat, 19 Jun 2021 22:25:16 +0000

What is Swagger? OpenAPI?

Swagger/OpenAPI allows us to document and collaborate with our users, specifically it allows to define the resources, parameters, types, fields and everything that describes the APIs we are building. Swagger and OpenAPI are two different things, it's better explained on the original blog post, but the idea is basically this:

OpenAPI: Specification
Swagger: Tools for implementing the specification

Implementing OpenAPI 3

Using Swagger 2.0 in Go well-known to be supported by packages like github.com/go-swagger/go-swagger and github.com/swaggo/swag however it gets more complicated when trying to use something much more recent like OpenAPI 3, in those cases really we have a few packages we can use:

github.com/getkin/kin-openapi/openapi3: to generate OpenAPI 3.0 documentation, and
github.com/deepmap/oapi-codegen: to generate Go client and server boilerplate from OpenAPI 3 specifications.

For generating the OpenAPI 3.0 document, we are going to be using the getkin/kin-openapi/openapi3 package, our example already defines a function that does that for us.

This function is long and it could a turn off for a lot of people, however I like it the way it is because it allows me to explicitly indicate the values I need, there's no magic (like in go-swagger or swagger/swag for example), it's a pro/con depending on how you see it because everything it's more manual.

In the end, the code needed to represent our API will be equivalent to the code written to build that structure. For example, taking the basic OpenAPI details, it looks like:

// NewOpenAPI3 instantiates the OpenAPI specification for this service.
func NewOpenAPI3() openapi3.Swagger {
    swagger := openapi3.Swagger{
        OpenAPI: "3.0.0",
        Info: &openapi3.Info{
            Title:       "ToDo API",
            Description: "REST APIs used for interacting with the ToDo Service",
            Version:     "0.0.0",
            License: &openapi3.License{
                Name: "MIT",
                URL:  "https://opensource.org/licenses/MIT",
            },
            Contact: &openapi3.Contact{
                URL: "https://github.com/MarioCarrion/todo-api-microservice-example",
            },
        },
        Servers: openapi3.Servers{
            &openapi3.Server{
                Description: "Local development",
                URL:         "http://0.0.0.0:9234",
            },
        },
    }

    // ... more code ...

With that function defined and with a helper binary we call go generate to build the YAML and JSON files we need to describe our API.

In practice the code in that cmd/openapi-gen/main.go looks basically like this:

func main() {
    swagger := rest.NewOpenAPI3()

    // openapi3.json
    data, _ := json.Marshal(&swagger)

    _ = os.WriteFile(path.Join(output, "openapi3.json"), data, 0644) // XXX: explicitly ignoring errors

    // openapi3.yaml
    data, _ = yaml.Marshal(&swagger)

    _ = os.WriteFile(path.Join(output, "openapi3.yaml"), data, 0644) // XXX: explicitly ignoring errors
}

Last thing is to make those files available:

func RegisterOpenAPI(r *mux.Router) {
    swagger := NewOpenAPI3()

    r.HandleFunc("/openapi3.json", func(w http.ResponseWriter, r *http.Request) {
        // ... code here ...
    }).Methods(http.MethodGet)

    r.HandleFunc("/openapi3.yaml", func(w http.ResponseWriter, r *http.Request) {
        // ... code here ...
    }).Methods(http.MethodGet)
}

Implementing Swagger UI

We built out OpenAPI 3 files, now as part of our HTTP handlers we are going to allow our users to interact with the Swagger UI to invoke our API, this is something that you may or not want to have in production, I personally prefer only allowing internal environments to support this UI for testing purposes.

To support the Swagger UI our your API we need to download all the dist files from the original repository and then embed them as part of your API as a new handler, for example copying the files over to cmd/rest-server/static/swagger-ui, and then embedding those using the new embed package included in Go 1.16, using something like:

//go:embed static
var content embed.FS


func main() {
    // ... other code ...

    r := mux.NewRouter()

    fsys, _ := fs.Sub(content, "static")
    r.PathPrefix("/static/").Handler(http.StripPrefix("/static/", http.FileServer(http.FS(fsys))))

    srv := &http.Server{
        Handler: r,
        // ... other code ...
    }

    log.Fatal(srv.ListenAndServe())
}

With that code in place we will be able to request http://address:port/static/swagger-ui and load our API using the OpenAPI 3 file we generated previously, one really important thing to change is the index.html file to refer to the local openapi3.json file and perhaps you want to generate that file depending on environment so it always points to the right HTTP URL.

Generating Client and Serve code from OpenAPI 3

Another interesting thing we can do after generating our OpenAPI 3 documentation is to generate boilerplate that represents Go types matching the original API, for that we use a package we mentioned earlier: github.com/deepmap/oapi-codegen. The way it works is like this:

We install the generator:

go install github.com/deepmap/oapi-codegen/cmd/oapi-codegen@v1.5.1

Then using go generate when generate our types:

//go:generate oapi-codegen -package openapi3 -generate types  -o ../../pkg/openapi3/task_types.gen.go openapi3.yaml
//go:generate oapi-codegen -package openapi3 -generate client -o ../../pkg/openapi3/client.gen.go     openapi3.yaml

Which in our example will create a bunch of types in the pkg package that then we can use to programmatically build some code to interact with out API, like the following example:

func main() {
    client, _ := openapi3.NewClientWithResponses("http://0.0.0.0:9234") // XXX: explicitly ignoring errors

    priority := openapi3.Priority_low

    respC, _ := client.CreateTaskWithResponse(context.Background(), // XXX: explicitly ignoring errors
        openapi3.CreateTaskJSONRequestBody{
            Dates: &openapi3.Dates{
                Start: newPtrTime(time.Now()),
                Due:   newPtrTime(time.Now().Add(time.Hour * 24)),
            },
            Description: newPtrStr("Sleep early"),
            Priority:    &priority,
        })

    // ... other code ...

Parting words

Documenting REST APIs in Go using Swagger 2.0 is relatively well supported and easy to do, there are a few different alternatives, however the concern you may have is that you're depending on technologies that are already old, if you want to explore the most recent alternatives like OpenAPI 3 things get more complicated, because the options are much more manual and really state of the art, which is a fair concern for people looking for long term solutions.

So what's the best approach? The way I see it is, if you're not willing to invest resources trying out new state-of-the-art tools then using Swagger 2.0 is your answer; however if you're willing to contribute back to the community exploring the OpenAPI 3 options is better because in the end it benefits everybody.

DEV Community: Mario Carrion

Microservices in Go: Events and Background jobs using Kafka

What is Kafka?

How does Kafka work?

Publisher implementation using a Repository

Consumer implementation

Conclusion

Recommended Reading

Learning Go: Context package

What is in the context package?

Deadlines

Cancellation signals

Request-scoped values

Conclusion

Recommended Reading

Building Microservices in Go: Events and Background jobs using RabbitMQ

What is RabbitMQ?

How does RabbitMQ work?

Publisher implementation using a Repository

Subscriber implementation

Conclusion

Recommended Reading

Why you should use/learn Go as hiring manager/individual contributor.

Hiring Manager

What are the cons?

What are the pros?

Individual Contributor

What are the cons?

What are the pros?

Conclusion

Recommended reading

Building Microservices in Go: Searching with Elasticsearch

What is Elasticsearch?

Using Elasticsearch in Go

Using elastic/go-elasticsearch

Conclusion

Recommended reading

Building Microservices in Go: Graceful Shutdown

Using signal.NotifyContext

Implementing Graceful Shutdown in HTTP Servers

Conclusion

Building Microservices in Go: Containerization using Docker

What is Docker?

How to use multi-stage builds?

Using Docker Compose for local development

Conclusion

Building Microservices in Go: OpenTelemetry

What is OpenTelemetry?

Using OpenTelemetry in Go

Metrics

Tracing

Logs

Conclusion

Building Microservices in Go: REST APIs: Implementing and Dealing with errors

Introduction to errors

Implementing a custom error type with state

Conclusion

Building Microservices in Go: REST APIs: Putting it all together

Putting it All Together

Types to match HTTP resources

Custom Go Types to describe JSON payloads

Document your APIs

Conclusion

Building Microservices in Go: REST APIs - Versioning

What is versioning in software?

What is Semantic Versioning?

How can we implement versioning for REST APIs?

Versioning using a path

Versioning using subdomains

Versioning using query arguments

Versioning using headers

Conclusion

Recommended Reading

Building Microservices in Go: REST APIs - OpenAPI 3 and Swagger UI

What is Swagger? OpenAPI?

Implementing OpenAPI 3

Implementing Swagger UI

Generating Client and Serve code from OpenAPI 3

Parting words

Recommended Reading

What is in the `context` package?

Using `elastic/go-elasticsearch`

Using `signal.NotifyContext`