DEV Community: Karan Kumar

Protocol Buffers and GRPC in Go

Karan Kumar — Mon, 06 Sep 2021 16:32:08 +0000

We will cover:

Protocol Buffers
Protocol Buffer Language
Compiling a protocol buffer with protoc
GRPC

The code can be found here GitHub

Protocol Buffers

Protocol buffers is a data exchange format similar to JSON. Protobuf vs JSON Both are for serialization, however, the key difference is that Protobuf is binary data –interchange format whereas JSON stores data in human-readable text format.

Protocol Buffers are strongly typed. As per definition by Google: You can update your datastructure without breaking deployed programs that are compiled against the old datastructure format. Interesting right? It is, we will see how that works.

Protocol Buffers allow us to define the data contract between multiple systems. Once a proto-buff file has beenn defined, we can compile it to a target programming language. The output of the compilation will be classes and functions of the target programming language. In Go, protocol buffers can be transported over different transports, such as HTTP/2
and Advanced Message Queuing Protocol (AMQP).

Protocol Buffer Language

A protocol buffer is a file, which when compiled, will generate a file accessible to the targetted programming language. In go, it will be a .go file which will be a structs mapping.

Let us write a simple message in protobuf:



syntax 'proto3'

message UserInterace {
  int      index         = 1;
  string   firstName     = 2;
  string   lastName      = 3;
}

Here we just define a message type called UserInterface. It we were to write the same using JSON:



{
  "index": 0,
  "firstName": "John",
  "lastName": "Doe"
}

The field names are changed to comply with the JSON style guide, but the essence and structure are the same.

But, what are the sequential numbers(1,2,3) in the protobuf file?

Those are the ordering tags used to serialize and deserialize proto-bufs between two systems. It tells the system to write the data in that particular order with the specified types. So when this proto-buf is compiled for targetted language Go, it will be a struct with the empty default values.

Different types that are used in protobuf:

Scalar
Enumerations
Nested

Scalar Values

Exmaples of scalar type values: int, int32, int64, string, bool etc. These types are converted to the corresponding language types after the compilation.

Since we are using Go in our case, the equivalent types in Go for these scalar types are:

Enumerations (enums)

Lets take an example of a proto file using enums:



syntax 'proto3'
message Schedule {
  enum Days {
    SUNDAY = 0;
    MONDAY = 1;
    FRIDAY = 2;
  }
}

And in case we want to assign the same values to multiple enum members:



syntax 'proto3'
message Schedule {
  enum Days {
    option allow_aias = true; 👈
    UNKNOWN  = 0;
    ACTIVE   = 1;
    INACTIVE = 1;
  }
}

repeated field is equavalent to array/list:



message CarInfo {
  string type = 1;
  repeated string cars = 2;
}

This means, the cars could be []string like ["bmw", "toyota", "honda"].

Nested Fields

We can also use message as a type for another message.

Example:



message User{
  string firstName  = 1;
  string lastName  = 2;
  repeated Comment comments= 3;
}

message Comment{
  int id = 1;
}

Compiling Protocol Buffer with protoc

To transfer data between the systems, we will make use of the compiled files from the proto proto files. We will make use of the structs (gotten from the compiled files) to create the binary data.

Steps we will follow:

Install the protoc comman-line tool and the proto library
Write .proto file
Compile the file for Go target language
Import the structs from the generated file and create data using those
Serialize the data into binary format and send it to the other system
On the remote machine, de-serialize the data and consume it

We will install he protoc command line from https://github.com/protocolbuffers/protobuf/releases

I am on windows, so I will install download the latest stable package and set the environment variable from Edit the system environment variable setting in the control panel.

Download and unzip (for Windows) : https://github.com/protocolbuffers/protobuf/releases/download/v3.17.3/protoc-3.17.3-win64.zip

I will extract it in the C:\Program Files\protoc folder (by creating the protoc folder). It must now have bin folder.
Now search for Edit the system environment variable setting on start menu, double click on Path in the list.
Now click on New and then Browse...
Browse until C:\Program Files\protoc\bin and click ok.
Now open a fresh terminal and type protoc --version to confirm the installation. The output must be:



$ protoc --version
libprotoc 3.17.3

For MAC and Linux

On mac

$ brew install protobuf

On Ubuntu or Linux, we can copy protoc to the /usr/bin folder:

Make sure you grab the latest version

curl -OL https://github.com/protocolbuffers/protobuf/releases/download/v3.17.3/protobuf-all-3.17.3.zip

Unzip

unzip protoc-3.11.3-linux-x86_64.zip -d protoc3

Move only protoc* to /usr/bin/

sudo mv protoc3/bin/protoc /usr/bin/protoc

After installing and setting up the command line tool, make sure you are able to access it from your terminal:



$ protoc --version
libprotoc 3.17.3

Now in our project directory, create a new folder protofiles and then in it let us create a proto file representing/modeling a person's information:

person.proto



syntax = "proto3"
package protofiles;
option go_package = "./";

message Person {
  string     name     =    1;
  int32      id       =    2;
  string     email    =    3;
  repeated   PhoneNumber  phones = 4;

  enum PhoneType {
    MOBILE  =  0;
    HOME    =  1;
    WORK    =  2;
  }

  message PhoneNumber {
    string      number  = 1;
    PhoneType   type    = 2;
  }
}

message AddressBook {
  repeated   Person  people = 1;
}

So we just created two main messages called Person and AddressBook. The AddressBook contains the list of Persons.
A person has a name, id, email and list of PhoneNumbers.

The second line package protofiles is the package name for go to compile.

To compile our person.proto proto-buf file, cd to the protofiles directory and run:

go get -u github.com/golang/protobuf/protoc-gen-go
protoc-gen-go is a plugin for the Google protocol buffer compiler to generate Go code.
protoc --go_out=. *.proto
this will create a Go target file in the present working directory from where the command is run (the dot) and make use of all the proto files to do so

This will generate a person.pb.go file. If you open this file you will see that it contains the auto generated code for us.
This will have multiple getter and setter methods for the structs to get and set the values.

Once done, make sure you push the repository on github to import the package in the main.go file.

Now let us write code to create Person struct from the auto generated file/package(person.pb.go) and serialize it into a buffer string using the proto package.

main.go



package main

import (
    "fmt"
    pb "github.com/karankumarshreds/GoProto/protofiles"
    "google.golang.org/protobuf/proto"
)

func main() {

    // using the profo created struct
    p := &pb.Person{
        Id: 1234,
        Name: "John Doe",
        Email: "test@test.com",
        Phones: []*pb.Person_PhoneNumber{
            {Number: "555-444", Type: pb.Person_HOME},
        },
    }

    // Serializing the struct and assigning it to body
    body, _ := proto.Marshal(p)

    // De-serializing the body and saving it to p1 for testing
    p1 := &pb.Person{}
    _ = proto.Unmarshal(body, p1)

    fmt.Println("Original struct loaded from proto file:", p)
    fmt.Println("Marshalled proto data: ", body)
    fmt.Println("Unmarshalled struct: ", p1)

}

Let us run the code now using go run main.go:



$ go run main.go
Original struct loaded from proto file: name:"John Doe" id:1234
email:"test@test.com" phones:{number:"555-444" type:HOME}


Marshalled proto data:  [10 8 74 111 104 110 32 68 111 101 16
210 9 26 13 116 101 115 116 64 116 101 115 116 46 99 111 109 34
11 10 7 53 53 53 45 52 52 52 16 1]

Unmarshalled struct:  name:"John Doe" id:1234 email:"test@test.com"
phones:{number:"555-444" type:HOME}

The second output is the binary bytes which has been serialized into by the proto library. This serialized binary data needs a medium to move between the two or more systems. This is where gRPC kicks in. Using gRPC (Google Remote Procedure Call), a server and client(not frontend) can talk which each other in the protocol buffer format.

GRPC

GRPC is a transport mechanism that sends and receives messages (protocol buffers) between two systems. The two parties are referred to as server and client.

The main advantage of gRPC is that it can be understood by multiple programming languages (via their respective grpc packages mostly) making the communication easy between different tech stacks

We need to install the grpc Go library and a protoc-gen plugin before writing the
services. Install them using the following commands:

go get google.golang.org/grpc

go get -u github.com/golang/protobuf/protoc-gen-go (already did in the previous section)

In this section we will create a money transaction service which will communicate over GRPC:

Create a proto-buf with the definistion of service and messages
Compile the protocol buffer file
Use the generated file package to create a gRPC server
Create a gRPC client to talk to the server

We will follow the SAME steps to create protobuf and compile package as we did in the last example.

Let us create a transaction.proto file nad put it in the protofiles directory.



syntax = "proto3";
package protofiles;
option go_package = "./";

message TransactionRequest {
  string    from   =   1;
  string    to     =   2;
  float     amount =   3;
}

message TransactionResponse {
  bool     confirmation = 1;
}

service MoneyTransaction {
  rpc MakeTransaction(TransactionRequest) returns (TransactionResponse) {}
}

The new keyword service defines the GRPC service. Here we are defining another type (type of function) for our RPC system, which will take in a type of TransactionRequest and return a TransactionResponse. Once compiled using protoc, the compiled file will contain an interface to invoke this function.

Now let us cd into the parent directory to the protofiles directory and run the command to compile the transaction.proto:



$ ls

protofiles/

$ protoc -I protofiles/ protofiles/transaction.proto --go_out=plugins=grpc:protofiles

NOTE This time we have used a grpc plugin to compile the package.

Now ls protofiles/ to confirm if the go package has been compiled:



-a----        06-09-2021     16:13           7672 transaction.pb.go
-a----        06-09-2021     16:13            357 transaction.proto

Now let us setup the GRPC server. The code explanation is done in the code comments:

Create a folder and file server/main.go



package main

import (
    "fmt"
    "net"
    "log"
    pb "github.com/karankumarshreds/GoProto/protofiles"
    "golang.org/x/net/context"
    "google.golang.org/grpc"
)

type server struct{}

func main() {

    // NewServer creates a gRPC server which has no service registered and has not started
    // to accept requests yet.
    s := grpc.NewServer()
    lis, err := net.Listen("tcp", ":8000")
    if err != nil {
        log.Fatalf("Failed to listen: %v", err)
    }

    // We are making use of the function that compiled proto made for us to register
    // our GRPC server so that the clients can make use of the functions tide to our
    // server remotely via the GRPC server (like MakeTransaction function)

    // The first argument is the grpc server instance
    // The second argument is the service who's methods we want to expose (in our case)
    // we have put it in this program only
    pb.RegisterMoneyTransactionServer(s, &server{})

    // Serve accepts incoming connections on the listener lis, creating a new ServerTransport
    // and service goroutine for each. The service goroutines read gRPC requests and then
    // call the registered handlers to reply to them.
    err = s.Serve(lis)
    if err != nil {
        log.Fatalf("Failed to serve: %v", err)
    }

}

// [ctx] is used by the goroutines to interact with GRPC
// [in] is the type of TransactionRequest
/*
    This function signature matches the service that we mentioned in the protobuf
*/
func (s *server) MakeTransaction(ctx context.Context, in *pb.TransactionRequest) (*pb.TransactionResponse, error) {
    // Business logic will come here
    fmt.Println("Got amount ", in.Amount)
    fmt.Println("Got from ", in.From)
    fmt.Println("For ", in.To)
    // Returning a response of type Transaction Response
    return &pb.TransactionResponse{Confirmation: true}, nil
}

This is it for the server side. The idea is that if the client makes a request to invoke the MakeTransaction function remotely, the server should go ahead and execute it (here it will only print the data received).

Now let us write down code for the client side as well:

Folder and file : client/main.go



package main

import (
    "log"
    pb "github.com/karankumarshreds/GoProto/protofiles"
    "golang.org/x/net/context"
    "google.golang.org/grpc"
)

// grpc server address
const address = "localhost:8000"

func main() {
    // Set up connection with the grpc server
    conn, err := grpc.Dial(address, grpc.WithInsecure())
    if err != nil {
        log.Fatalf("Error while making connection, %v", err)
    }

    // Create a client instance
    c := pb.NewMoneyTransactionClient(conn)

    // Lets invoke the remote function from client on the server
    c.MakeTransaction(
        context.Background(),
        &pb.TransactionRequest{
            From: "John",
            To: "Alice",
            Amount: float32(120.15),
        },
    )
}

This client code will make connection to the grpc server we created through the GRPC package and make use of the protofile to run the MakeTransaction function remotely.

Now if we run both together. First we will run the server code:

cd server
go run main.go

This will start the server code, now open a new terminal and start the client code as well. As soon as we do that, we should see the logs on the server side terminal.

cd client
go run main.go

That's it, the client now made a connection with the server and invoked the MakeTransaction function remotely.
The server must have the following logs:



$ go run main.go
Got amount  120.15
Got from  John
For  Alice

Congratulations, you have successfully created the server and client side grpc connection. A gRPC client can request a gRPC server to perform a computationheavy/secure operation. The client can be a mobile device too.

The code can be found here GitHub

RPC Implementation in Go

Karan Kumar — Sat, 04 Sep 2021 13:23:22 +0000

What is RPC?

RPC (Remote Procedure Call) is an inter-process communication that exchanges information between various distrubuted systems (servers).
It is a protocol that one program can use to request a service from a program located on some other node/server/computer/system on the network without having to udnerstand the network's details.

In simple words, a computer A can call a function(procedures) in another computer B remotely. Hence, Remote Procedure Call.

The basic steps for the entire process are as:

Client (system A) decides the function name and arguments to send
Client send the same to the RPC Server by dialing the connection
The RPC server receives the function name and arguments
RPC server invokes/executes the function on the remote system B
The client collects the data from the request

As you can see, it is a synchronous process.

Go provides a library for both RPC Server and RPC Client
In the above diagram, the client sends the arguments and the reply pointer. Since it is a pointer, the server can modify it as per the request. The client will then use the data filled into the pointer.

Creating an RPC server

Code for this blog can be found here GitHub

Let us now create an RPC server that will send the UTC server time to the RPC client. We will use net/rpc and net/http standard packages for this example.

NOTE The RPC Server and RPC Client should agree upon:

Arguments passed
Value Returned

And must have exactly same types for both server and client

Let us create an Args struct to hold the arguments received from the client and TimeServer type using which we will register our function on RPC server for clients to run it.



type Args struct {}

type TimeServer int64

Now let us create the GiveTimeServer function which will be invoked from the client.



func (t *TimeServer) GiveServerTime(args *Args, reply *int64) error {
    // Set the value at the pointer got from the client
    *reply = time.Now().Unix()
    return nil
}

Now let us register the methods listening on type TimeServer on the RPC server:



/* server.go */

func main() {
    timeserver := new(TimeServer)
    // Register the timeserver object upon which the GiveServerTime
    // function will be called from the RPC server (from the client)
    rpc.Register(timeserver)
    // Registers an HTTP handler for RPC messages
    rpc.HandleHTTP()
    // Start listening for the requests on port 1234
    listener, err := net.Listen("tcp", ":1234")
    if err !=nil {
        log.Fatal("Listener error: ", err)
    }
    // Serve accepts incoming HTTP connections on the listener l, creating
    // a new service goroutine for each. The service goroutines read requests
    // and then call handler to reply to them
    http.Serve(listener, nil)
}

That's it from the server side.

Creating an RPC client

We will create the struct for Args (its empty in this example). And a reply variable which must have SAME type as that of server.



/* client.go */

package main

import (
    "log"
    "net/rpc"
)

type Args struct {}

func main() {
    // Address to this variable will be sent to the RPC server
    // Type of reply should be same as that specified on server
    var reply int64
    args := Args{}

    // DialHTTP connects to an HTTP RPC server at the specified network
    client, err := rpc.DialHTTP("tcp", "localhost"+":1234")
    if err != nil {
        log.Fatal("Client connection error: ", err)
    }

    // Invoke the remote function GiveServerTime attached to TimeServer pointer
    // Sending the arguments and reply variable address to the server as well
    err = client.Call("TimeServer.GiveServerTime", args, &reply)
    if err != nil {
        log.Fatal("Client invocation error: ", err)
    }

    // Print the reply from the server
    log.Printf("%d", reply)
}

That was pretty straight forward. We just created a client and connected it to the host and port on which server is listening on.

Then we used the Call function to invoke a function tied to the TimeServer type and passed in args and &reply pointer.

Now let us start the server.go program.



$ go run server.go

Now let us start the client.go program and as soon as we do that, we will see the server's reply of it's current UTC time:



$ go run client.go
2021/09/04 18:36:37 1630760797 // 👈

That's it. It's that simple. I hope you guys understood how the client and server connection works via RPC server. In future blogs, we will dive deeper into the same topic and cover more on RPC and also GRPC.

Code for this blog can be found here GitHub

Authentication in Go

Karan Kumar — Fri, 03 Sep 2021 19:24:53 +0000

How authentication works

A client sends the authentication request to the server with the credentials. The server validates the credentials with the database entry. If the match is successful, it writes something called cookie in the response.
This cookie will be sent back from the client in the subsequent requests to the server which is used by the servers to validate if the cookie attached is valid (on the basis of the one sent in the first place).

Sessions

A session is a way to record users authentication related payload in a cookie over a period of time.

Here's a diagram from book Handson restful services with Go:

When the user logs in in by sending valid credentials, the server attaches the cookie in the response. Then the client uses that cookie (saved in the browser or client service) to make future requests.
When a client makes a logout request by sending a API on the server, the server destroys the session in the response. The server can also place an expiration on cookies so that the session expires after a certain time if there is no activity.

The working code for this can be found on GitHub

Let us use gorilla/mux package to implement this workflow.

We will use the packages:

"github.com/gorilla/mux"
"github.com/gorilla/sessions"

Let us create a cookie store first from the sessions package

// store the secret key in env variable in production
var store = sessions.NewCookieStore([]byte("my_secret_key"))

This secret key is supposed to be a secret for the server. The cookie session is encrypted and decrypted using this key. This is how the server validates if the user/client is logged in with proper payload on the cookie or not.

First we will create three routes to implement the authentication example:

/login
/logout
/healthcheck (a test route that will be used by the logged in user)

Lets create the login handler. I will add relevant comments for code explanation:

func loginHandler(w http.ResponseWriter, r *http.Request) {
    if r.Method != "POST" {
        http.Error(w, "Method Not Supported", http.StatusMethodNotAllowed)
        return
    }
    // ParseForm parses the raw query from the URL and updates r.Form
    err := r.ParseForm()
    if err != nil {
        http.Error(w, "Please pass the data as URL form encoded", http.StatusBadRequest)
        return
    }

  // Get username and password from the parsed form
    username := r.Form.Get("username")
    password := r.Form.Get("password")

    // Check if user exists
    storedPassword, exists := users[username]
    if exists {
        // It returns a new session if the sessions doesn't exist
        session, _ := store.Get(r, "session.id")
        if storedPassword == password {
            session.Values["authenticated"] = true
            // Saves all sessions used during the current request
            session.Save(r, w)
        } else {
            http.Error(w, "Invalid Credentials", http.StatusUnauthorized)
        }
        w.Write([]byte("Login successfully!"))
    }

}

Now let us create the logout handler which will cater to the GET request. In this handler we will set the authenticated flag on the request session to false

func logoutHandler(w http.ResponseWriter, r *http.Request) {
    // Get registers and returns a session for the given name and session store.
    session, _ := store.Get(r, "session.id")
    // Set the authenticated value on the session to false
    session.Values["authenticated"] = false
    session.Save(r, w)
    w.Write([]byte("Logout Successful"))
}

Now let us implement the test handler which is serving the protected route : /healthcheck:

func healthcheck(w http.ResponseWriter, r *http.Request) {
    session, _ := store.Get(r, "session.id")
    authenticated := session.Values["authenticated"]
    if authenticated != nil && authenticated != false {
        w.Write([]byte("Welcome!"))
        return
    } else {
        http.Error(w, "Forbidden", http.StatusForbidden)
    return
    }
}

Now let us use the gorilla/mux library to hook up all the handlers in our main function:

func main() {
  r := mux.NewRouter()
    r.HandleFunc("/login", loginHandler).Methods("POST")
    r.HandleFunc("/logout", logoutHandler).Methods("GET")
    r.HandleFunc("/healthcheck", healthcheck).Methods("GET")
    // modifying default http import struct to add an extra property
    // of timeout (good practice)
    httpServer := &http.Server{
        Handler: r,
        Addr: "127.0.0.1:8000",
        WriteTimeout: 15 * time.Second,
    }
    log.Fatal(httpServer.ListenAndServe())
}

Now let us login with postman on the login route and see if we are able to do so:

We can see we are able to login with 200 response and cookies are also set. If we check the cookie set by the server, we will see the name of the cookie is session'id which we set from the server side.

Now let us make another request to see if we are able to validate the authenticated user by hitting the protected route healthcheck:

Yes, we are!

Now let us hit the logout route and see

Yes, we can logout.

Now last thing, let us try to hit the /healthcheck again and we should be FORBIDDEN to do so:

And yes, it works! Congratulations, you have successfully created a session based authentication system using Go and Mux package.

In the upcoming blog, we will learn how to make use of Redis to persist the user sessions. Till then, stay tuned!

The working code for this can be found on GitHub

Middlewares in Go

Karan Kumar — Fri, 03 Sep 2021 05:05:46 +0000

Today we will learn how to implement middlewares in Go and also we will learn how to chain the middlewares in an efficient way without using any third party package.

The code for this can be found here GitHub

Middleware

Middleware is an entity that intercepts the server's request/response life cycle. In simple words, it is a piece of code that runs before/after the server caters to a request with a response.
A middleware can do the following:

Process the request before running business logic (authentication)
Modify the request to the next handler function (attaching payload)
Modify the response for the client
Logging.... and much more

Basic Middleware

Let's write a basic route handler

func main() {
    http.Handle("/", handler)
    http.HandleAndServe(":8000", nil)
}

func handler(w http.ResponseWriter, r *http.Request) {
    fmt.Prinln("Executing the handler")
    w.Write([]byte("OK"))
}

This piece of code simply returns "OK" response to the GET request at http://localhost:8000/.

Now let us create a simple middleware that will be a function that intercepts the request -> response lifecycle.

func middleware(originalHandler http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        fmt.Println("Running before handler")
        w.Write([]byte("Hijacking Request "))
        originalHandler.Serve(w, r)
        fmt.Println("Running after handler")
    })
}

Explanation: This middleware function expects a function (our handler in this case) of type handler and will return a handler after tweaking the request response flow.

So what is does is:

Runs Println function
Writes to the response "Hijacking Request"
Serves the original handler which was passed as an argument
Runs a Println function

Let us hook this up with the main function:

func main() {
    // converting our handler function to handler 
    // type to make use of our middleware 
    myHandler := http.Handlerfunc(handler)
    http.Handle("/", middleware(myHandler)) // 👈
    http.HandleAndServe(":8000", nil)
}

func handler(w http.ResponseWriter, r *http.Request) {
    fmt.Prinln("Executing the handler")
    w.Write([]byte("OK"))
}

func middleware(originalHandler http.Handler) http.Handler {
  return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        fmt.Println("Running before handler")
        w.Write([]byte("Hijacking Request "))
        originalHandler.Serve(w, r)
        fmt.Println("Running after handler")
  })
}

Now if we hit it with a GET request at http://localhost:8000 we will get

Client response:

Hijacking Request OK

👆 This shows the middleware added the response "Hijacking Request" to the original response by the handler, that is "OK".

Server logs:

Running before handler
Executing the handler 
Running after handler

Real world example

Now let us take what we have learned and build upon it. This middleware example has two goals:

Write a middleware that makes sure request has Header "Content-Type" application/json
Write a middleware that adds current server time to the reponse cookie

Middleware #1

func filterContentType(handler http.Handler) http.Handler {
  return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request){
    if r.Header.Get("Content-Type") != "application/json" {
      w.WriteHeader(http.StatusUnsupportedMediaType)
      w.Write([]byte("405 - Header Content-Type incorrect"))
      return
    }
    handler.ServeHTTP(w, r)
  })
}

Middleware #2

func setTimeCookie(handler http.Handler) http.Handler {
  return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request){
    // Cookie here is a struct that represents an HTTP
    // cookie as sent in the Set-Cookie header of HTTP request
    cookie := http.Cookie{
      Name: "Server Time (UTC)" // can be anything
      Value: strconv.Itoa(int(time.Now().Unix()))
      // 👆 converted time to string
    }
    // now set the cookie to response 
    http.SetCookie(w, &cookie)
    handler.ServeHTTP(w, r)
  })
}

Now let us create a handler to handle the POST request, and then we will use the middlewares:

Handler

type Person struct {
    Firstname string
    Lastname string
}

// main handler 
func postHandler(w http.ResponseWriter, r *http.Request) {
    if r.Method != "POST" {
        w.WriteHeader(http.StatusMethodNotAllowed)
        w.Write([]byte("405 - Method Not Allowed"))
        return
    }

    var p Person
    decoder := json.NewDecoder(r.Body)
    err := decoder.Decode(&p)
    if err != nil {
        w.WriteHeader(http.StatusInternalServerError)
        w.Write([]byte("500 - Internal Server Error"))
        return
    }
    defer r.Body.Close()

    fmt.Printf("Got firstName and lastName as %s, %s",
    p.Firstname, p.Lastname)
    w.WriteHeader(http.StatusOK)
    w.Write([]byte("201 - Created"))
}

Now let we will (in the main function):

Take the middlewares
Chain them together
Wrap them around the handler

func main() {
    myHandler := http.HandlerFunc(postHandler)
    chain := filterContentType(setTimeCookie(myHandler)) // 👈
    http.Handle("/", chain)
    http.ListenAndServe(":8000", nil)
}

filterContentType(setTimeCookie(myHandler))
This will return the handler and run the middlewares in the order:

filterContentType
setTimeCookie
... and then our handler

Let us test this now:

curl -H "Content-Type: application/json" -X POST http://localhost:8000/city -d '{"firstname": "John", "lastname": "Doe"}'

The server will respond with

201 - Created

Now let us test the Header middleware

curl -i -X POST http://localhost:8000/city -d '{"firstname": "John", "lastname": "Doe"}'

The server will respond with

415 - Unsupported Media Type

That is exactly what we wanted. Also you can use postman or curl command to check if the response has the attached cookie as well. And it will because of the other middleware.

But chaining these middlewares is not a neat process, imagine we had 5 middlewares, the chaining would look like:

chain := m1(m2(m3(m4(m5(handler)))))

👆 This is not what we want, so let us create our own chaining middleware handling logic.

Chaining Middlewares

Goal is to use chain := m1(m2(m3(m4(m5(handler))))) as chain := CreateChain(m1, m2, m3, m4, m5).Then(handler)

Let us write a pseudo code for that we want to do:

We need a CreateChain function that takes an Slice/List of middlewares
We need a Then function that would be used as a method on Chain type object that will do run : m1(m2(m3(m4(m5(handler)))))

Let us create a struct for a Middleware and Chain (which is slice/list of middleware):

type Middleware func(http.Handler) http.Handler
type Chain []Middleware

Now let us write function CreateChain

// returns a Slice of middlewares 
func CreateChain(middlewares ...Middleware) Chain {
    var slice Chain
    return append(slice, middlewares...)
}

Now let us write function

func (c Chain) Then(originalHandler http.Handler) http.Handler {
    if originalHandler == nil {
        originalHandler = http.DefaultServeMux
    }

    for i := range c {
        // Same as to m1(m2(m3(originalHandler)))
        originalHandler = c[len(c) -1 -i](originalHandler)
    }
    return originalHandler
}

So here, the for loop will loop through each middleware from in the Slice/List of middlewares and keep it wrap itself around the originalHandler passed into the function.

Now we can use this in the main function as:

func main() {
    myHandler := http.HandlerFunc(postHandler)
    chain := CreateChain(filterContentType, setTimeCookie).Then(myHandler) // 👈
    http.Handle("/", chain)
    http.ListenAndServe(":8000", nil)
}

The code for this can be found here GitHub

I hope that was helpful. Feel free to create a PR on the code repo if you find any issues or improvements.

Memory allocations in Go

Karan Kumar — Wed, 01 Sep 2021 19:44:37 +0000

To understand how memory allocations in Go works, we need to understand the types of memories in programming context, which are Stack and Heap.
If you are familiar with typical memory representation of C, you must already be aware of these two terms.

Stack vs Heap

Stack: The stack is a memory set aside as a scratch space for the execution of thread. When a function in called, a block is reserved on top of the stack for local variables and some bookkeeping data. This block of memory is referred to as a stack frame. Initial stack memory allocation is done by the OS when the program is compiled. When a function returns, the block becomes unused and can be used the next time any function is called (in the world of JS this is similar to function's execution context).
The stack is always reserved in LIFO (last in first out), the most recent block added will be freed(marked as unused) first. The size of the memory allocated to the function and it's variable on the stack is known to the compiler and as soon as the function call is over, the memory is de-allocated.

Heap: In heap there is no particular order to the way the items are placed. Heap allocation requires manual housekeeping of what memory is to be reserved and what is to be cleaned. The heap memory is allocated at the run time. Sometimes the memory allocator will perform maintenance tasks such as defragmenting allocated memory (fragmenting: when small free blocks are scattered, but when request for large memory allocation comes, there is no free memory left in heap even though small free blocks combined may be large. this is bad!) OR garbage collecting (identifying at runtime when memory is no longer in scope and deallocating it).

What makes one faster?

The stack is faster because all free memory is always contiguous. No list needs to be maintained of all the segments of free memory, just a single pointer to the current top of the stack.

In case of goroutines (kind of simultaneously executing go functions) we have multiple stack memories for each go routines as shown in the below figure:

Variable allocations

But how do we know which memory will the variable be assigned in the go program out of Stack and Heap?

NOTE: Th term free (in the diagrams) refer to the memory that is acquired by a stack frame (valid memory). And unused means the invalid memory in the stack.

1 Let us consider the following code. The function main has its local variables n and n2. main function is assigned a stack frame in the stack. Same goes for the function square.

2 Now as soon as the function square returns the value, the variable n2 will become 16 and the memory function square is NOT cleaned up, it will still be there and marked as invalid (unused).

3 Now when the Println function is called, the same unused memory on stack left behind by the square function is consumed by the Println function. (take a look at the memory address for a)

With Pointers

1 Let us do the same thing with pointers. Here we have a main function which passes the reference to the variable to a function that increments the value.

2 Now as function inc dereferences the pointer and increments the value that it points to, and does its work, the stack frame of inc is again unused/invalid (freed for other functions allocation).

3 as the function Println runs, it acquires the memory that was freed up by the inc function as shown in the below figure

This is where Go Compiler kicks in 🚩
Sharing down of the variables (passing references) typically stays on the stack. Notice the word typically. This is because, the GO Compiler takes the decision whether a referenced variable needs to stay on the stack or on the heap.

But when would the referenced variable be put on Heap?

Let us understand that.

Let us consider an example where we are returning pointers.

1 So we have a function main that has a variable n who's value is assigned by a function answer which returns a pointer to it's local variable. This is how the stack frame allocation is done initially for both the functions

2 Now when the function answer executes and returns the pointer, the address for x is assigned to the variable n in the main function and the answer function's stack frame gets freed up (unused)

Here's the catch 🚩

We have a problem here, we have a pointer pointing down to the unused (invalid memory) in the stack. But how is that a problem?

Let us see what happens when the Println function is called.

3 Println function takes the space freed up by the answer function (notice the memory address) and takes reference to the returned value and divides it by 2 (making it 21).

This is the problem here, the value which n was pointing to (which was originally 42) has been overwritten by the Println call which made it 21. And since Println took over the memory address of answer function (after answer function freed up the space), now that memory has the value 21 (instead of 42)

What is the solution?

Thanks to Go compiler, we do not have to worry about this. Go compiler is smart enough to handle this.

This is what really happens:

Compiler knows it was NOT safe to leave the pointer variable on the stack. So what it does is, it declares x (from the answer function) somewhere on the Heap

This means when the Println function is called, which changes the value to half, it will not clobber the value of x. This is called Escaping To The Heap which is done during the compile time.

Therefore, sharing up (returning pointers) typically escapes to the Heap.

Concurrency Patterns in Go

Karan Kumar — Fri, 20 Aug 2021 17:05:36 +0000

Before we even begin to understand what "concurrency" is in Go, we need to make sure we understand that concurrency is not parallelism. Parallelism is means parallel execution of processes where as concurrency is about design. With concurrency you can:

Design your program as a collection of independent processes.
Design these processes to eventually run in parallel.
Design your code so that the outcome is always the same.

Do not worry if you don't understand the above explanation, we will take a deep dive into concurrency patterns in this blog with real examples.

What can we achieve with Concurrency?

We can have multiple groups of code(workers) running independent tasks.
We can eliminate race conditions.
We can eliminate deadlocks.
The more workers we have, the faster the execution is.

Goroutines

To understand concurrency, we must understand what Goroutines are. A Goroutine is a function or a method which executes independently and simultaneously in connection with any other Goroutines present in your program.
So we could also say, every concurrently running process in Go language is known as a Goroutine.

func main (){
    go makeHttpCall("http://xyz.com")
//  👆 makes this method a GoRoutine
}

func makeHttpCall(link string) {
    _, err := http.Get(link)
    if err == nil {
        fmt.Printf("The link %v is up", link)
    }
}

Code explanation:

The main function invokes the makeHttpCall() function with a keyword go in front of it. This makes this function run on in a Goroutine. You can consider a Goroutine like a light weighted thread. The cost of creating Goroutines is very small as compared to a thread.

The main function also has its own routine which we do not have to define, known as main Goroutine. All the other Goroutines are working under the main Goroutine. If the main Goroutine is terminated, all the other Goroutines present in the program are also terminated.

Where are we going with this?

Let us say we want to fetch data from multiple links without using Goroutines.

func main() {
    // creating a slice of links 
    links := []string{
        "http://abc.com",
        "http://pqr.com",
        "http://xyz.com",
    }
    // fetching data from each link
    for _, link := range links {
        makeHttpCall(link)
    }
}

func makeHttpCall(link string) {
    _, err := http.Get(link)
    if err == nil {
        fmt.Printf("The link %v is up", link)
    }
}

Code explanation:

This code will iterate over the slice of links and sequentially make http calls on each of the links. In case on of the links takes x seconds to retrieve the response, the other main go routine will block for x seconds before it sends the next request.

We can easily make use of Goroutines to fix this. Let us see the code and then we will discuss how it helps us.

func main() {
    // creating a slice of links 
    links := []string{
        "http://abc.com",
        "http://pqr.com",
        "http://xyz.com",
    }
    // fetching data from each link
    for _, link := range links {
        go makeHttpCall(link) // 👈
    }
}

func makeHttpCall(link string) {
    _, err := http.Get(link)
    if err == nil {
        fmt.Printf("The link %v is up", link)
    }
}

Code explanation:

We made use of the same go keyword we discuss earlier to run the makeHttpCall function in its own Goroutine. Now the main Goroutine will not wait for the request to be resolve, rather it will keep on iterating and creating separate Goroutine for each invocation of makeHttpCall.

Here's the catch!

We might think that this solves the issue, right? But it doesn't. The output of this function would be:

👆 Absolutely nothing. Why is that? #[1]

This is because, the main go routine (tied to the main function by default) creates the Goroutine for each makeHttpCall function invocation. Once the iteration is completed, the main function continues to run and reaches the end. It doesn't wait for the other Goroutines to finish.
Remember, we discussed a few minutes ago "If the main Goroutine is terminated, all the other Goroutines present in the program are also terminated". This is exactly what happened. So how do we solve it?

To solve this, we need a way to communicate between these Goroutines and the main Goroutine. And to communicate between multiple Goroutines, we make use of something called channels.

Channels

Go provides a mechanism called a channel that is used to share data between goroutines. Channels act as a pipe between the goroutines and provide a mechanism that guarantees a synchronous exchange.

There are two types of channels:

Unbuffered channels (which we will be using for the example)
Buffered channels

Unbuffered channels are used to perform synchronous communication within the goroutines. These provide a guarantee that an exchange of the data is performed at the instant it is sent.

In go we declare the channels and we also must specify the data-type at the time of the channel declaration. The data-type is the type of the data that will be shared through the channel.

myChannel := make(chan string)

This means, this channel can be used to only share the data of type string.

Buffered channels are used to perform asynchronous communication within the goroutines.

myBufferedChannel := make(chan string, 10)

Buffered channels (you may skip this section)

In the buffered channels there is a capacity to hold one or more values before they're received. The sending and receiving is not performed synchronously and immediately.

The blocking cases:

The receive will block when there is no value in the channel to receive.
The send will block when there is no available buffer to place the value being sent.

Code example:

package main

import (
    "fmt"
    "io/ioutil"
    "log"
    "net/http"
    "sync"
)

func main() {

    // initializing a WaitGroup
    var wg sync.WaitGroup

    // adding 3 counts/buffer to the WaitGroup
    wg.Add(3)

    fmt.Println("Start Goroutines")
    go responseSize("https://www.golangprograms.com", &wg)
    go responseSize("https://stackoverflow.com", &wg)
    go responseSize("https://coderwall.com", &wg)

    // wait for goroutines to finish
    wg.Wait()
    fmt.Println("Terminating the main program")

}

// just prints the response size of the body returned
func responseSize(url string, wg *sync.WaitGroup) {
    // schedule the Done() call when the goroutine is finished
    defer wg.Done()

    fmt.Println("Step1: ", url)
    response, err := http.Get(url)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println("Step2: ", url)
    body, err := ioutil.ReadAll(response.Body)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println("Step3: ", len(body))
}

The output for the above program would be:

Start Goroutines
Step1:  https://coderwall.com
Step1:  https://www.golangprograms.com
Step1:  https://stackoverflow.com     
Step2:  https://stackoverflow.com
Step2:  https://www.golangprograms.com
Step3:  31857
Step3:  207321
Step2:  https://coderwall.com
Step3:  189752
Terminating the main program

This is quite intuitive how it worked. For the people who did not understand this, three different goroutines were spun up and the main program, waited (using wait group) for the all the goroutines to finish before terminating the program.

Back to the main topic 🎉

We learned about channels and how they act as pipes to communicate data within the goroutines. Let us continue with the issue at hand #[1], that is the how to stop code to from terminating before goroutines are finished executing and get access to which link is down or not.

So in this code, we will make use of channels and communicate the main goroutine (running by default in the main function) and the goroutine spun up during the helper function invocation:

func main() {
    // creating a channel to share string type data
    myChanel := make(chan string)

    // creating a slice of links 
    links := []string{
        "http://abc.com",
        "http://pqr.com",
        "http://xyz.com",
    }
    // fetching data from each link
    for _, link := range links {
        go makeHttpCall(link, myChanel) 
    }
    // listening for three messages coming from the chanel
    for i := 0; i <3; i++ {
        fmt.Printf("Link %v is up \n", <- myChanel)
    }
}

func makeHttpCall(link string, myChanel chan string) {
    _, err := http.Get(link)
    if err == nil {
        // sending the link name to the chanel 👈
        myChanel <- link
    }
}

The output of the above program is:

Link http://abc.com is up
Link http://xyz.com is up
Link http://pqr.com is up

Code explanation:

So here, we listened (3 times) for the message to receive (synchronously) from the goroutines from the channel.
In other words, the main function's goroutine waited for the chanel to receive a message, printed out the print statement, and then went on to receive the next message from the channel and repeated itself three times.

That's all there is to know the basics of goroutines and concurrency patterns. There is a lot more to learn. So, in the future blogs, we will take a deep dive on how everything is being handled behind the scenes. Until then, peace ✌