DEV Community: b0r

1. Getting started with Spring Framework - Spring in Action - book notes

b0r — Tue, 04 Jan 2022 18:24:46 +0000

Another month, another book.

To refresh my Spring Framework / Spring Boot knowledge (that I'm using on day-to-day basis), I've started reading an excellent Spring in Action, 6th edition published by Manning.

I'm not sure about you, but taking notes (writing/drawing) really helps me get the most out of the book, so I'm sharing everything I have with you (for further reference).

I also really like taking notes in Markdown format. The nice thing about Markdown is, that I can publish it on dev.to and get a nice HTML automatically generated/published for further reference!!

1. Getting started with Spring

This chapter covers

Spring and Spring Boot essentials
Initializing a Spring project
An overview of the Spring landscape

1.1 What is Spring?

Application Context

at its core, Spring offers a container, often referred to as the Spring application context, that creates and manages application components
these components, or beans, are wired together inside the Spring application context to make a complete application, much like bricks, mortar, timber...are bounded to make a house
application components are managed and injected into each other by spring application context

Dependency Injection

the act of wiring beans together
dependency injected application relies on a separate entity (container) to create and maintain all components and inject those into the beans that need them.
typically done through constructor args or property accessor methods

<bean id="inventoryService"
      class="com.example.InventoryService"
/>

<bean id="productService"
      class="com.example.ProductService">
      <constructor-arg ref="inventoryService"/>
</bean>

@Configuration
public class ServiceConfiguration {
  @Bean
  public InventoryService inventoryService() {
    return new InventoryService();
  }

  @Bean
  public ProductService productService() {
    return new ProductService(inventoryService());
  }
}

@Configuration

indicates that class provides beans to the Spring application context

@bean

indicates that returned object should be added as a bean in the application context

Component Scanning

Spring automatically discover components from an application's classpath and create them as bean in the Spring application context

Autowiring

Spring automatically injects the components with the other beans that they depend on

Spring Boot

most well-known enhancement is auto-configuration
- make reasonable guesses of what components need to be configured and wired together based on entries in the classpath, env vars,...

1.2 Initializing a Spring application

Initializing a Spring project with Spring Tool Suite

Taco Cloud
- an online app for ordering food
- dependencies:
- spring web
- spring dev tools
- thymeleaf

Exploring the build specification

parent pom provides dependency management for several libraries commonly used in Spring projects:

  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.5.3</version>
    <relativePath />
  </parent>

library version is inherited from the parent version
spring boot starter dependencies typically don't have any library code themselves, but instead transitively pull in other libraries
- you're able to think of your dependencies in terms of what capabilities they provide, rather than their library names
- you don't have to worry about the library version

Spring Boot Plugin

it provides a Maven goal to run the application
ensures that all deps. are included within the executable JAR file and available on the runtime classpath
produces a manifest file (contains metadata) in the JAR file that denotes the bootstrap class as the main class for the executable JAR

Bootstrapping the application

@SpringBootApplication

composite annotation that combines 3 other annotations:
- @SpringBootConfiguration (specialized form of the @Configuration)
- @EnableAutoConfiguration (automatically configure any component you might need)
- @ComponentScan (spring automatically discovers/registers components, services, controllers..)

Testing the application

$ ./mvnw package
...
$ java -jar target/taco-cloud-0.0.1-SNAPSHOT.jar

$ ./mvnw package
...
$ java -jar target/taco-cloud-0.0.1-SNAPSHOT.jar

A baseline application test

can be used to assert that the application starts

package tacos;

import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.SpringBootTest;

@SpringBootTest
public class TacoCloudApplicationTests {

  @Test
  public void contextLoads() {
  }

}

@SpringBootTest

tells JUnit to bootstrap the test with Spring Boot capabilities
ocmposite annotation:
- @ExtendWith(SpringExtension.class)

1.3 Writing a Spring application

Create Taco Cloud application homepage:

create controlle
create view template
write tests

Handling web requests

Spring MVC

controller - a class that handles req/resp
@Controller annotation
- identify class as a component for component scanning
home() method
@GetMapping
return "home"
- "home" is a logical name of a view
- template name is derivered from the logical view name /templates/home.html

Defining the view

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" 
      xmlns:th="http://www.thymeleaf.org">
  <head>
    <title>Taco Cloud</title>
  </head>

  <body>
    <h1>Welcome to...</h1>
    <img th:src="@{/images/TacoCloud.png}"/>
  </body>
</html>

Static content, e.g. images are kept in the /src/main/resources/static/

Testing the controller

perform the HTTP GET request for the root path '/'
- expect successful result (viewName = home, content = "Welcome to...")

package tacos;

import static org.hamcrest.Matchers.containsString;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.view;

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.test.web.servlet.MockMvc;

@WebMvcTest(HomeController.class)
public class HomeControllerTest {

  @Autowired
  private MockMvc mockMvc;

  @Test
  public void testHomePage() throws Exception {
    mockMvc.perform(get("/"))
      .andExpect(status().isOk())
      .andExpect(view().name("home"))
      .andExpect(content().string(
          containsString("Welcome to...")));
  }

}

@WebMvcTest

special annotation provided by spring boot
arranges the test to run in the context of a Spring MVC application
- arranges HomeController to be registered in Spring MVC so that you can send request to it
it doesn't start the server (mockin is good enough in this case)
the test class is injected with a MockMvc object for the test to drive the mockup

Building and running the application

./mvnw springBoot:run

Spring Boot application tend to bring everything they need with them and don't need to be deployed to some application server. Tomcat is a part of your application.

Getting to know Spring Boot DevTools

Spring DevTools provides developers with some handy development-time tools:

automatic application restart when code (or application properties) changes
automatic browser refresh
automatic disable of template caches
built in h2 console/DB

How it works?

there are 2 class loaders
- first one contains you Java code, property files that change frequently
- second one contains dependency libraries which aren't changed often
when change is detected, first class loader is automatically restarted

Let's review

initialized project
wrote controller
defined template
wrote simple test

The main benefit is that you can focus on the code that meets the requirements of an application, rather than on satisfying the demands of a framework <- "framework-less framework"

declare dependencies in pom.xml
- web
- thymeleaf

these two dependencies transitively bring in other dependencies:

spring mvc framework
embedded tomcat
thymeleaf and thymeleaf layout dialect
spring auto-configuration library

1.4 Surveying the Spring landscape

Spring Framework (Core)
- provides core container and dependency injection
- provides Spring MVC, a Spring's web framework, JDBC support, WebFlux (reactive)
Spring Boot
- provides starter dependencies and auto-configuration
- actuator (runtime insight into the inner workings of the application)
- flexible specification of env. properties
- additional testing support
- Spring Boot CLI (alternative programming model based on Groovy scripts)
Spring Date
- define data repositories as Java interfaces (sql, nosql, graph,..)
Spring Security
- authentication, authorization, API security
Spring Integration
- real time integration where data is processed as it's made available
Spring Batch
- batched integration
Spring Cloud
- check out Cloud Native Spring
Spring Native
- Spring Boot + GraalVM => native images

1.5 Sumary

spring aims to make developer challenges easy
- creating web apps, working with databases, securing applications, and microservices
spring boot builds on top of spring to make spring even easier
spring applications can be initialized using the spring initializer
beans (components) can be declared explicitly with Java or XML, discovered by component scanning, or automatically configured with spring boot auto-configuration

Nmap Go implementation - TCP port scan

b0r — Fri, 17 Dec 2021 15:06:02 +0000

I remember when I first started learning about computer networks. It was from the excellent Computer Networks, 5th Edition, Andrew S. Tanenbaum book. Book is accompanied by the University of Washington video course taught by David Wetherall. Video materials are available at: 👉 Tanenbaum, Wetherall Computer Networks 5e, Video Notes. 👈
Be sure to check them out, they are great!!

After reading a bunch of posts on dev.to on Nmap topic, e.g.:

I have decided to refresh my knowledge on computer networks by re-implementing Nmaps` basic functionalities in Go.

This is first post in the series of posts I'll use to record that journey.

Table of Contents:

n2map (noob network mapper)
1. TCP connect scan technique
n2map requirements
Implementation
1. Get target machine IP
2. Connect to the target machine (hard-coded port)
3. Connect to the target machine (user provided port)
4. Connect to the target machine (multiple ports)
5. Review
6. Make it go brrrr (parallel)
Conclusion

n2map (noob network mapper)

This project is called n2map (noob network mapper) and it will implement a subset of Nmaps` functionalities. That's port scanning functionality for now.

If we take a look at the Nmap documentation for port scanning we'll see that is supports a dozen or so port scan techniques:

TCP SYN scan (half-open scanning, doesn't open a full TCP connection)
TCP connect scan (full scanning, connect to port on the target machine)
UDP scans (sends UDP packet to every targeted port)
and many more..

n2map first functionality will add support to perform port scanning for single IP address. It will use a TCP connect scan technique.

TCP connect scan technique

In detail description of TCP connect scan technique is described in port scan techniques part in the Nmap documentation.

For this post, I think it's enough to know that a TCP connect scan technique is a technique that performs a standard TCP three-way handshake to establish the connection, and does the same for closing the connection.

Let's see what packets are sent if connect:

from localhost (192.168.1.6)
to target machine on the http://scanme.nmap.org/ (45.33.32.156) on port 80

We see green rectangle that represents packets sent to establish the connection. We also see red rectangles representing the packets sent to close the connection.

In case a connection can't be established, we'll see following packets sent over the network:

n2map requirements

I would like to use n2map the same way I use nmap:

via terminal
by providing target machine IP address
by providing a port range to scan
by using the TCP connect scan technique
- this is currently only supported scan technique in n2map so no additional flags are added at the moment

The run command should looks like this: n2map -p 80-433 127.0.0.1

Implementation

Get target machine IP

First thing we need to have to perform a port scan is a target machine IP address. IP address will be provided as an argument to the n2map runtime as follows: n2map 127.0.0.1

Following Go code shows how to implement that.



package main

import (
    "flag"
    "fmt"
    "os"
    "time"
)

func main() {
    flag.Parse()
        // IP is provided as an argument at position 0
    if ip := flag.Arg(0); ip != "" {
        dt := time.Now()
        fmt.Printf("Starting n2map v0.1 at %s\n", dt.Format(time.UnixDate))
        fmt.Printf("n2map scan report for %s\n", ip)
        fmt.Printf("PORT\tSTATE\n")
    } else {
        fmt.Println("error : IP address not provided")
        os.Exit(1)
    }
}

Result



% go run main.go 127.0.0.1
Starting n2map v0.1 at Fri Dec 17 13:27:55 CET 2021
n2map scan report for 127.0.0.1
PORT    STATE

Connect to the target machine (hard-coded port)

Once we have a target machine IP address we are ready to make a connection. Luckily, Go provides a Dial function that can be used to connect to a target machine. It can be used like this: Dial("tcp", "198.51.100.1:80")

Let's update our code to reflect the changes:



        port := 80
        addr := fmt.Sprintf("%s:%d", ip, port)
        _, err := net.Dial("tcp", addr)
        if err == nil {
            fmt.Printf("%s\t%s\t\n", port, "open")
        } else {
            fmt.Printf("%s\t%s\t\n", port, "closed")
        }

Result



% go run main.go 127.0.0.1
Starting n2map v0.1 at Fri Dec 17 13:27:55 CET 2021
n2map scan report for 127.0.0.1
PORT    STATE
80      closed

Notice that we have hard-coded port value 80, which means we need to rerun the n2map for each port we want to scan. We can do better than that.

Connect to the target machine (user provided port)

To make it possible to provide port we will introduce a new -p flag.



    func main() {

    var port string
    flag.StringVar(&port, "p", "80", "port to scan")
    flag.Parse()

    if ip := flag.Arg(0); ip != "" {
        dt := time.Now()
        fmt.Printf("Starting n2map v0.1 at %s\n", dt.Format(time.UnixDate))
        fmt.Printf("n2map scan report for %s : [%s]\n", ip, port)
        fmt.Printf("PORT\tSTATE\n")

        addr := fmt.Sprintf("%s:%d", ip, port)
        _, err := net.Dial("tcp", addr)
        if err == nil {
            fmt.Printf("%d\t%s\t\n", port, "open")
        } else {
            fmt.Printf("%d\t%s\t\n", port, "closed")
        }

    } else {
        fmt.Println("error : IP address not provided")
        os.Exit(1)
    }

}

Now we are able to use n2map with provided port as:
n2map -p 80 127.0.0.1

Result



% go run main.go -p 80 127.0.0.1
Starting n2map v0.1 at Fri Dec 17 13:27:55 CET 2021
n2map scan report for 127.0.0.1 : [80]
PORT    STATE
80      closed

This is still now good enough! We want to be able to scan not only one port per n2map run but multiple ports.

Connect to the target machine (multiple ports)

To make that possible we are going to extend the existing port flag functionality to include a range of ports to scan by:

extending provided port runtime argument to support port ranges like 80-100 (scan ports >= 80 and <= 100)
making a Dial call for each port in provided range



func main() {

    var portRangeFlag string
    flag.StringVar(&portRangeFlag, "p", "80", "port range to scan")
    flag.Parse()

    if ip := flag.Arg(0); ip != "" {
        dt := time.Now()
        fmt.Printf("Starting n2map v0.1 at %s\n", dt.Format(time.UnixDate))
        fmt.Printf("n2map scan report for %s : [%s]\n", ip, portRangeFlag)
        fmt.Printf("PORT\tSTATE\n")

        portRange := strings.Split(portRangeFlag, "-")
        startPort, _ := strconv.Atoi(portRange[0])
        endPort, _ := strconv.Atoi(portRange[1])

        for port := startPort; port <= endPort; port++ {
            addr := fmt.Sprintf("%s:%d", ip, port)
            _, err := net.Dial("tcp", addr)
            if err == nil {
                fmt.Printf("%d\t%s\t\n", port, "open")
            } else {
                fmt.Printf("%d\t%s\t\n", port, "closed")
            }
        }

    } else {
        fmt.Println("error : IP address not provided")
        os.Exit(1)
    }
}

Now we are able to use n2map with provided port as:
n2map -p 80-81 127.0.0.1

Result



% go run main.go -p 80-81 127.0.0.1

Starting n2map v0.1 at Fri Dec 17 13:46:36 CET 2021

n2map scan report for 127.0.0.1 : [80-81]

PORT    STATE

80      closed


81      open

Review

Nice! If we check the initial requirements:

I would like to use n2map the same way I use nmap:

via terminal

by providing target machine IP address

by providing a port range to scan

by using the TCP connect scan technique

this is currently only supported scan technique in n2map so no additional flags are added at the moment

we can see that all the requirements are implemented.

Make it go brrrr (parallel)

Not in the requirement list, but non less important is the time this implementation takes to scan multiple ports, or even all 65535 ports. It's very, very slow.

If you have read any of my previous posts on Go Channel Patterns you should have enough knowledge to make improvements needed to speed up this process.

Battle plan for that is:

scan ports (make TCP connection)
- create a worker goroutines that will do the net.Dial call for specific port
- create a manager goroutine that will iterate over a portStart and portEnd range, and send each port to one of the worker goroutines
- create a channel used to pass data between manager and worker goroutines
print results
- make results channel used by worker goroutines to pass the results to the manager goroutine
- use for-range loop to iterate over results channel and print out the results
- create a new supervisor goroutine that will close the results channel once there are no more ports to process by worker goroutines
- use sync.WaitGroup to tell supervisor when to close the results channel

Conclusion

In this post, TCP connect scan port scanning technique was described (as described by Nmap). In addition, simple implementation was provided.

Readers are encouraged to try to speed the port scanning process up by using one of the Go concurrency primitives (goroutines, channels...).

Resources:

Header Photo by Ricardo Esquivel from Pexels

Go Channel Patterns - Cancellation

b0r — Wed, 15 Dec 2021 08:31:54 +0000

To improve my Go Programming skills and become a better Go engineer, I have recently purchased an excellent on-demand education from Ardan Labs. Materials are created by an expert Go engineer, Bill Kennedy.

// Detect dark theme var iframe = document.getElementById('tweet-1443663502808395780-646'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1443663502808395780&theme=dark" }

I have decide to record my process of learning how to write more idiomatic code, following Go best practices and design philosophies.

This series of posts will describe channel patterns used for orchestration/signaling in Go via goroutines.

Cancellation Pattern

The main idea behind the Cancellation Pattern is to have a limited amount of time to perform work. If limit is reached, the work is ignored.

We have:

a context with specified timeout
a buffered channel that provides signaling semantic
a worker goroutine that does the work
a manager goroutine that waits on (which comes first):
- worker goroutine signal (that the work is completed)
- context timeout signal

Example

In Cancellation Pattern we have a limited amount of time to perform some work.

Imagine we are in the ice cream making business and we have:

a manager (main goroutine) that get and holds a scoop of the ice cream in one hand
- he holds out his other hand (communication channel) and waits for an employee (worker goroutine) to pass him the ice cream cone so he can sell the ice cream
an employee (worker goroutine) that needs some time to get the ice cream cone so he can pass it to the mangers' hand
- if employee takes too much time to get the ice cream cone, the ice cream that manager holds will melt, so he won't need the ice cream cone anymore and the manager won't hold his hand anymore
an employee is now stuck with the ice cream cone in his hand and can't perform any other work (goroutine leak)
- to fix this employee and the manager decided to use new communication channel (e.g. desk buffered channel) so that employee can complete his work, regardless of the managers' hand

Use Case

Good use case for this pattern is any request to a remote service, e.g. database request, API request or whatever request that can block. Since we don't want our request to block forever, we use timeout to cancel it.

Feel free to try the example on Go Playground

package main

import (
    "context"
    "fmt"
    "math/rand"
    "time"
)

func main() {
    // a duration that sets the max time to perform the operation

    // e.g 150 ms to get the ice cream cone
    duration := 1 * time.Millisecond

    // context.Background() returns a non-nil, empty Context.
    // It is never canceled, has no values, and has no deadline.
    // It is typically used by the main function, initialization, and tests,
    // and as the top-level Context for incoming requests.
    emptyCtx := context.Background()

    // Create new context from emptyCtx + add timeout of 150 ms
    // ctx is new context with timeout
    // cancel is a function that releases resources associated with context

    // e.g. ticker that the manager uses to check if he gets the ice cream cone fast enough
    ctx, cancel := context.WithTimeout(emptyCtx, duration)

    // Canceling this context releases resources associated with it,
    // so code should call cancel as soon as the operations running in
    // this Context complete

    // e.g. command manager uses to cancel the context (unit of work - getting ice cream cone)
    defer cancel()

    // IMPORTANT:
    // Make buffered channel of size 1, and type string which provides signaling semantics.
    // Buffered channel ensures that the worker goroutine can perform the send operation
    // and complete even if there is no-one on the receive side.
    // e.g.
    // - if worker goroutine does NOT finish in 150ms
    // -- main goroutine will continue
    // -- this will cause worker goroutine leak
    //    since there is no-one goroutine to receive the sent signal (so it blocks and waits)

    // e.g. used to prevent employee from being blocked if he doesn't complete the work in 150ms
    ch := make(chan string, 1)

    // create worker goroutine
    go func() {
        // Simulate the idea of unknown latency (do not use in production).
        // Don't forget that context timeout is 150 ms, but this can take up to 200 ms.

        // e.g. employee reaches out for the ice cream cone from the box
        time.Sleep(time.Duration(rand.Intn(200)) * time.Millisecond)

        // send signal when work is done
        // e.g. employee passes ice creeam cone to the managers' hand
        ch <- "paper"
    }()

    // select-case allow us to perform multiple channel operations
    // at the same time, on the same goroutine

    // e.g. manager waits for ice cream cone, or for 150 ms timer to time out
    select {

    // best case scenario:
    // receive a result from worker goroutine in under the 150 ms

    // e.g. employee finds and passes the ice cream cone to the manager
    case d := <-ch:
        fmt.Println("work complete", d)

    // ctx.Done() call starts the 150ms duration clock ticking.
    // If 150 ms passes before the worker goroutine finishes, this println will be executed

    // e.g. manager doesn't wait for employee to get the ice cream cone anymore
    case <-ctx.Done():
        fmt.Println("work cancelled")
    }
}

Result (1st execution)

go run main.go

work complete paper

Result (2st execution)

go run main.go

work cancelled

Conclusion

In this article, cancel channel pattern was described. In addition, simple implementation and use case were provided.

Readers are encouraged to check out excellent Ardan Labs education materials to learn more.

Resources:

Go Channel Patterns - Drop

b0r — Tue, 14 Dec 2021 19:40:44 +0000

// Detect dark theme var iframe = document.getElementById('tweet-1468963384280293380-547'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1468963384280293380&theme=dark" }

I have decide to record my process of learning how to write more idiomatic code, following Go best practices and design philosophies.

This series of posts will describe channel patterns used for orchestration/signaling in Go via goroutines.

Drop Pattern

The main idea behind Drop Pattern is to have a limit on the amount of work that can be done at any given moment.

We have:

a buffered channel that provides signaling semantic
a number of worker goroutines
a manager goroutine that:
- takes the work and sends it to the worker goroutine
- if there is more work than worker goroutines can process and buffered channel is full, manager goroutine will drop the work

Example

In Drop Pattern we have a limited amount of work (capacity) we can do in a day.

We have predefined number of employees that will do the work (worker goroutines).

We also have a manager (main goroutine) that generates work (or gets work from some predefined list of work).

Manager notifies employee about the work via communication channel ch. Employee gets the work from the communication channel ch.

Communication channel ch is capable of holding a limited amount of work "in the queue" (buffered channel). We say a channel has a limited capacity. Once channel ch is full, manager can't send new work and instead decides to DROP that unit of work and tries to send a new unit of work to the channel (maybe this time there is some space on the ch). Manager will do that as long as there is available work to do.

Use Case

Good use case for this pattern would be a DNS server. A DNS server has a limited capacity, or limited amount of requests that it can process at any given moment. If there are more requests sent to the DNS server we can decide to overload and kill the server, or to DROP new requests until DNS server has capacity to process the request.

Feel free to try the example on Go Playground

package main

import (
    "fmt"
    "time"
)

func main() {
    // capacity
    // max number of active requests at any given moment
    const cap = 100

    // buffered channel is used to determine when we are at capacity
    ch := make(chan string, cap)

    // a worker goroutine
    // e.g. an employee
    go func() {
        // for-range loop used to check for new work on communication channel `ch`
        for p := range ch {
            fmt.Println("employee : received signal :", p)
        }
    }()

    // amount of work to do
    const work = 200

    // range over collection of work, one value at the time
    for w := 0; w < work; w++ {
        // select-case allow us to perform multiple channel operations
        // at the same time, on the same goroutine
        select {

        // signal/send work into channel
        // start getting goroutines busy doing work
        // e.g. manager sends work to employee via buffered communication channel
        //      if buffer is full, default case is executed
        case ch <- "paper":
            fmt.Println("manager : sent signal :", w)

        // if channel buffer is full, drop the message
        // allow us to detect that we are at capacity
        // e.g. manager drops the unit of work
        default:
            fmt.Println("manager : dropper data :", w)
        }
    }

    // once last piece of work is submitted, close the channel
    // worker goroutines will process everything from the buffer
    close(ch)
    fmt.Println("manager : sent shutdown signal")

    time.Sleep(time.Second)
}

Result

go run main.go

manager : sent signal : 0
manager : sent signal : 1
manager : sent signal : 2
manager : sent signal : 3
manager : sent signal : 4
...
manager : dropper data : 101
manager : dropper data : 102
...
employee : received signal : paper
employee : received signal : paper
...
employee 0 : received shutdown signal
...
employee : received signal : paper
employee : received signal : paper

Conclusion

In this article, drop channel pattern was described. In addition, simple implementation and use case were provided.

Readers are encouraged to check out excellent Ardan Labs education materials to learn more.

Resources:

Go Channel Patterns - Fan Out Bounded

b0r — Tue, 14 Dec 2021 12:38:31 +0000

// Detect dark theme var iframe = document.getElementById('tweet-1468963384280293380-10'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1468963384280293380&theme=dark" }

I have decide to record my process of learning how to write more idiomatic code, following Go best practices and design philosophies.

This series of posts will describe channel patterns used for orchestration/signaling in Go via goroutines.

Fan Out Bounded Pattern

The main idea behind Fan Out Bounded Pattern is to have a limited number of goroutines that will do the work.

We have:

a fixed number of worker goroutines
a manager goroutine that creates/reads the work and sends it to the worker goroutines
a buffered channel that provides signaling semantics
- used to notify worker goroutines about available work

Example

In Fan Out Bounded Pattern we have a fixed amount of employees that will do the work (worker goroutines).

We also have a manager (main goroutine) that generates work (or gets work from some predefined list of work). Manager notifies employee about work via communication channel ch. Employee gets the work from the communication channel ch.

Communication channel ch is capable of holding a limited amount of work "in the queue" (buffered channel). Once channel ch is full, manager can't send new work until employee takes work from the queue.

Once there is no more work for employees, manager closes the communication channel ch.

Once all the employees (worker goroutines) complete the work, they notify the manager and they all go home.

Use Case

Good use case for this pattern would be batch processing, where we have some amount of work to do, but we have a limited number of executors. Each executor does the job of processing multiple units of work.

Feel free to try the example on Go Playground

package main

import (
    "fmt"
    "sync"
)

func main() {
    // 5 peaces of work to do
    work := []string{"paper1", "paper2", "paper3", "paper4", "paper5"}

    // number of worker goroutines that will process the work
    // e.g. fixed number of employees
    // g := runtime.NumCPU()
    g := 2

    // use waitGroup to orchestrate the work
    // e.g. each employee take one seat in the office to do the work
    //      in this case we have two seats taken
    var wg sync.WaitGroup
    wg.Add(g)

    // make buffered channel of type string which provides signaling semantics
    // e.g. manager uses this channel to notify employees about available work
        // if buffer is full, manager can't send new work
    ch := make(chan string, g)

    // create and launch worker goroutines
    for e := 0; e < g; e++ {
        go func(emp int) {
            // execute this statement (defer) when this function/goroutine terminates
            // decrement waitGroup when there is no more work to do
            // do this once for-range loop is over and channel is closed
            // e.g. employee goes home
            defer wg.Done()

            // for-range loop used to check for new work on communication channel `ch`
            for p := range ch {
                fmt.Printf("employee %d : received signal : %s\n", emp, p)
            }

            // printed when communication channel is closed
            fmt.Printf("employee %d : received shutdown signal\n", emp)
        }(e)
    }

    // range over collection of work, one value at the time
    for _, wrk := range work {
        // signal/send work into channel
        // start getting goroutines busy doing work
        // e.g. manager sends work to employee via buffered communication channel
        //      if buffer is full, this operation blocks
        ch <- wrk
    }

    // once last piece of work is submitted, close the channel
    // worker goroutines will process everything from the buffer
    close(ch)

    // guarantee point, wait for all worker goroutines to finish the work
    // e.g. manager waiits for all employees to go home before closing the office
    wg.Wait()

}

Result

go run main.go

employee 1 : received signal : paper1
employee 1 : received signal : paper3
employee 1 : received signal : paper4
employee 1 : received signal : paper5
employee 1 : received shutdown signal
employee 0 : received signal : paper2
employee 0 : received shutdown signal

Conclusion

In this article, fan out buffered channel pattern was described. In addition, simple implementation was provided.

Readers are encouraged to check out excellent Ardan Labs education materials to learn more.

Resources:

Go Channel Patterns - Fan Out Semaphore

b0r — Mon, 13 Dec 2021 18:02:17 +0000

// Detect dark theme var iframe = document.getElementById('tweet-1468657044907515910-954'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1468657044907515910&theme=dark" }

I have decide to record my process of learning how to write more idiomatic code, following Go best practices and design philosophies.

This series of posts will describe channel patterns used for orchestration/signaling in Go via goroutines.

Fan Out Semaphore Pattern

The main idea behind Fan Out Semaphore Pattern is to have:

everything we had in the Fan Out Pattern:
- a buffered channel that provides a signaling semantics
- a goroutine that starts multiple (child) goroutines to do some work
- a multiple (child) goroutines that do some work and use signaling channel to signal the work is done
PLUS the addition of a:
- new semaphore channel used to restrict the number of child goroutines that can be schedule to run

Example

In Fan Out Pattern we have multiple employees that have some work to do.

We also have a manager (main goroutine) that waits on that work to be done. Once each employee work is done, employee notifies manager by sending a signal (paper) via communication channel ch.

In Fan Out Semaphore Pattern we have an additional constraint in terms of maximum number of employees that can do work at any given moment.

Explanation

For example, we have 100 employees, but only 10 available free seats in the office space. It doesn't matter that 100 employees are available to do the work when we only have adequate space for 10 employees at any given moment. Other 90 employees have to wait until on of those 10 finish the work and frees the seat.

Good use case for this pattern would be batch processing, where we have some amount of work to do, but we want to limit the number of active executors at any given moment.

Feel free to try the example on Go Playground



package main

import (

    "fmt"

    "math/rand"

    "time"

)

func main() {

    emps := 10

<span class="c">// buffered channel, one slot for every goroutine</span>
<span class="c">// send side can complete without receive (non-blocking)</span>
<span class="n">ch</span> <span class="o">:=</span> <span class="nb">make</span><span class="p">(</span><span class="k">chan</span> <span class="kt">string</span><span class="p">,</span> <span class="n">emps</span><span class="p">)</span>

<span class="c">// max number of RUNNING goroutines at any given time</span>
<span class="c">// g := runtime.NumCPU()</span>
<span class="n">g</span> <span class="o">:=</span> <span class="m">2</span>
<span class="c">// buffered channel, based on the max number of the goroutines in RUNNING state</span>
<span class="c">// added to CONTROL the number of goroutines in RUNNING state</span>
<span class="n">sem</span> <span class="o">:=</span> <span class="nb">make</span><span class="p">(</span><span class="k">chan</span> <span class="kt">bool</span><span class="p">,</span> <span class="n">g</span><span class="p">)</span>

<span class="k">for</span> <span class="n">e</span> <span class="o">:=</span> <span class="m">0</span><span class="p">;</span> <span class="n">e</span> <span class="o">&lt;</span> <span class="n">emps</span><span class="p">;</span> <span class="n">e</span><span class="o">++</span> <span class="p">{</span>
    <span class="c">// create 10 goroutines in the RUNNABLE state</span>
    <span class="c">// one for each employee</span>
    <span class="k">go</span> <span class="k">func</span><span class="p">(</span><span class="n">emp</span> <span class="kt">int</span><span class="p">)</span> <span class="p">{</span>

        <span class="c">// when goroutine moves from RUNNABLE to RUNNING state</span>
        <span class="c">// send signal/value inside a `sem` channel</span>
        <span class="c">// if `sem` channel buffer is full, this will block</span>
        <span class="c">// e.g. employee takes a seat</span>
        <span class="n">sem</span> <span class="o">&lt;-</span> <span class="no">true</span>
        <span class="p">{</span>
            <span class="c">// simulate the idea of unknown latency (do not use in production)</span>
            <span class="c">// e.g. employee does some work</span>
            <span class="n">time</span><span class="o">.</span><span class="n">Sleep</span><span class="p">(</span><span class="n">time</span><span class="o">.</span><span class="n">Duration</span><span class="p">(</span><span class="n">rand</span><span class="o">.</span><span class="n">Intn</span><span class="p">(</span><span class="m">200</span><span class="p">))</span> <span class="o">*</span> <span class="n">time</span><span class="o">.</span><span class="n">Millisecond</span><span class="p">)</span>

            <span class="c">// once work is done, signal on ch channel</span>
            <span class="n">ch</span> <span class="o">&lt;-</span> <span class="s">"paper"</span>
            <span class="n">fmt</span><span class="o">.</span><span class="n">Println</span><span class="p">(</span><span class="s">"employee : sent signal : "</span><span class="p">,</span> <span class="n">emp</span><span class="p">)</span>
        <span class="p">}</span>

        <span class="c">// once all work is done pull the value from the `sem` channel</span>
        <span class="c">// give place to another goroutine to do the work</span>
        <span class="c">// e.g. employee stands up and free up seat for another employee</span>
        <span class="o">&lt;-</span><span class="n">sem</span>
    <span class="p">}(</span><span class="n">e</span><span class="p">)</span>
<span class="p">}</span>

<span class="c">// wait for all employee work to be done</span>
<span class="k">for</span> <span class="n">emps</span> <span class="o">&gt;</span> <span class="m">0</span> <span class="p">{</span>
    <span class="c">// receive signal sent from the employee</span>
    <span class="n">p</span> <span class="o">:=</span> <span class="o">&lt;-</span><span class="n">ch</span>

    <span class="n">emps</span><span class="o">--</span>
    <span class="n">fmt</span><span class="o">.</span><span class="n">Println</span><span class="p">(</span><span class="n">p</span><span class="p">)</span>
    <span class="n">fmt</span><span class="o">.</span><span class="n">Println</span><span class="p">(</span><span class="s">"manager : received signal : "</span><span class="p">,</span> <span class="n">emps</span><span class="p">)</span>

<span class="p">}</span>



}

Result



go run main.go

employee : sent signal :  9

paper

manager : received signal :  9

employee : sent signal :  4

paper

manager : received signal :  8

employee : sent signal :  1

paper

manager : received signal :  7

employee : sent signal :  2

paper

manager : received signal :  6

employee : sent signal :  3

paper

manager : received signal :  5

employee : sent signal :  8

paper

manager : received signal :  4

employee : sent signal :  6

paper

manager : received signal :  3

employee : sent signal :  5

paper

manager : received signal :  2

employee : sent signal :  0

paper

manager : received signal :  1

employee : sent signal :  7

paper

manager : received signal :  0

Conclusion

In this article, fan out semaphore channel pattern was described. In addition, simple implementation was provided.

Readers are encouraged to check out excellent Ardan Labs education materials to learn more.

Resources:

Go Channel Patterns - Pooling

b0r — Mon, 13 Dec 2021 11:31:39 +0000

// Detect dark theme var iframe = document.getElementById('tweet-1464978639355789317-199'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1464978639355789317&theme=dark" }

I have decide to record my process of learning how to write more idiomatic code, following Go best practices and design philosophies.

This series of posts will describe channel patterns used for orchestration/signaling in Go via goroutines.

Pooling Pattern

The main idea behind Pooling pattern is to have:

a channel that provides a signaling semantics
- unbuffered channel is used to have a guarantee a goroutine has received a signal
multiple goroutines that pool that channel for work
a goroutine that sends work via channel

Example

In this example you are a manager, and you hire a bunch of new employees.

Employees don't know immediately what do to, and they wait for manager to give them some work. The are looking at the channel ch to see if there is some work to do.

Once manager finds some work for the employees, it notifies them by sending a signal (paper) via communication channel ch.

First available employee that sees a signal from the channel ch, takes and completes the work.

After that employee completes the work, he is once again available to do more work, and he starts waiting for a new signal on channel ch.

Feel free to try the example on Go Playground

package main

import (
    "fmt"
    "time"
)

func main() {
    // make channel of type string which provides signaling semantics
    // unbuffered channel provides a guarantee that the
    // signal being sent is received
    ch := make(chan string)

    // number of goroutines to create, numCPU() is a good starting point
    //g := runtime.NumCPU()
    g := 3

    for e := 0; e < g; e++ {
        // a new goroutine is created for each employee
        go func(emp int) {
            // employee waits for the signal that there is some work to do
                        // all goroutines are blocked on the same channel `ch` recieve
            for p := range ch {
                fmt.Printf("employee %d : received signal : %s\n", emp, p)
            }

            // when all work is sent, manager notifies all employees by closing the channel
            // once the channel is closed, employee breaks out of the for-range loop
            fmt.Printf("employee %d : revieved shutdown signal\n", emp)
        }(e)
    }

    // amount of work to be done
    const work = 10

    for w := 0; w < work; w++ {
        // when work is ready, we send signal from the manager to the employee
        // sender (manager) has a guarantee that the worker (employee) has received the signal
        // manager doesn't care about which employee received a signal,
        // since all employees are capable of doing the work
        ch <- "paper"

        fmt.Println("manager : sent signal :", w)
    }

    // when all work is sent the manages notifies all employees by closing the channel
    // unbuffered channel provides a guarantee that all work has been sent
    close(ch)
    fmt.Println("manager : sent shutdown signal")

    time.Sleep(time.Second)

}

Result (1st execution)

go run main.go

employee 2 : recieved signal : paper
manager : sent signal : 0
manager : sent signal : 1
manager : sent signal : 2
manager : sent signal : 3
employee 1 : recieved signal : paper
employee 1 : recieved signal : paper
employee 2 : recieved signal : paper
manager : sent signal : 4
manager : sent signal : 5
manager : sent signal : 6
employee 1 : recieved signal : paper
employee 1 : recieved signal : paper
employee 0 : recieved signal : paper
employee 2 : recieved signal : paper
manager : sent signal : 7
manager : sent signal : 8
manager : sent signal : 9
manager : sent shutdown signal
employee 0 : recieved signal : paper
employee 0 : revieved shutdown signal
employee 2 : revieved shutdown signal
employee 1 : recieved signal : paper
employee 1 : revieved shutdown signal

Conclusion

In this article, pooling channel pattern was described. In addition, simple implementation was provided.

Readers are encouraged to check out excellent Ardan Labs education materials to learn more.

Note

Depending on the country you are coming from, Ardan Labs education might be a little bit expensive. In that case you can always contact them and they will provide you a link to their scholarship form.

Resources:

Go Channel Patterns - Wait For Task

b0r — Mon, 13 Dec 2021 07:39:41 +0000

// Detect dark theme var iframe = document.getElementById('tweet-1443663502808395780-122'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1443663502808395780&theme=dark" }

I have decide to record my process of learning how to write more idiomatic code, following Go best practices and design philosophies.

This series of posts will describe channel patterns used for orchestration/signaling in Go via goroutines.

Wait For Task Pattern

The main idea behind Wait For Task pattern is to have:

a channel that provides a signaling semantics
a goroutine that waits for task so it can do some work
a goroutine that sends work to the previous goroutine

Example

In this example we have an employee (a goroutine) that doesn't know immediately what to do. The employee waits for manager to give him some work to do.
Once manager finds some work for the employee, it notifies employee by sending a signal (paper) via communication channel ch.

Feel free to try the example on Go Playground

package main

import (
    "fmt"
    "math/rand"
    "time"
)

func main() {
    // make channel of type string which provides signaling semantics
    // unbuffered channel provides a guarantee that the 
    // signal being sent is received
    ch := make(chan string)

    // goroutine 'a' that waits for some work => employee
    go func() {
        // employee waits for signal that it has some work to do
        p := <-ch
        fmt.Println("employee : received signal : ", p)
    }()

    // simulate the idea of unknown latency (do not use in production)
    // e.g. manager is thinking what work to pass to the employee
    time.Sleep(time.Duration(rand.Intn(500)) * time.Millisecond)


    // when work is ready, send signal form manager to the employee
    // sender (employee) has a guarantee that the worker (employee)
    // has received a signal
    ch <- "paper"

    fmt.Println("manager : sent signal")

    time.Sleep(time.Second)
}

Result (1st execution)

go run main.go
manager : sent signal
employee : received signal :  paper

Conclusion

In this article, wait for task channel pattern was described. In addition, simple implementation was provided.

Readers are encouraged to check out excellent Ardan Labs education materials to learn more.

Note

Resources:

Go Channel Patterns - Fan Out

b0r — Sun, 12 Dec 2021 21:35:44 +0000

// Detect dark theme var iframe = document.getElementById('tweet-1455534157275205640-221'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1455534157275205640&theme=dark" }

I have decide to record my process of learning how to write more idiomatic code, following Go best practices and design philosophies.

This series of posts will describe channel patterns used for orchestration/signaling in Go via goroutines.

Fan Out Pattern

The main idea behind Fan Out Pattern is to have:

a channel that provides a signaling semantics
- channel can be buffered, so we don't wait on immediate receive confirmation
a goroutine that starts multiple (other) goroutines to do some work
a multiple goroutines that do some work and use signaling channel to signal that the work is done

Example

In this example we have multiple employees that have some work to do. We also have a manager (main goroutine) that waits on that work to be done. Once each employee work is done, employee notifies manager by sending a signal (paper) via communication channel ch.

Feel free to try the example on Go Playground

package main

import (
    "fmt"
    "math/rand"
    "time"
)

func main() {

    employees := 3

    // make channel of type string which provides signaling semantics
    // buffered channel is used so no goroutine blocks a sending operation
    // if two goroutines send a signal at the same time, channel performs synchronization
    ch := make(chan string, employees)

    for e := 0; e < employees; e++ {

        // start goroutine that does some work for employee e
        go func(employee int) {

            // simulate the idea of unknown latency (do not use in production)
            time.Sleep(time.Duration(rand.Intn(200)) * time.Millisecond)
                        // when work is done send signal
            ch <- "paper"
            fmt.Println("employee : sent signal :", employee)
        }(e)
    }

    // goroutine 'main' => manager
    // goroutines 'main' and employee goroutines are executed in parallel

    // wait for all employee work to be done
    for employees > 0 {
        // receive signal sent from the employee
        p := <-ch

        employees--
        fmt.Println(p)
        fmt.Println("manager : received signal :", p)
    }

    time.Sleep(time.Second)
}

Result

go run main.go

employee : sent signal : 1
paper
manager : received signal : paper
employee : sent signal : 2
paper
manager : received signal : paper
employee : sent signal : 0
paper
manager : received signal : paper

Conclusion

In this article, fan out channel pattern was described. In addition, simple implementation was provided.

Readers are encouraged to check out excellent Ardan Labs education materials to learn more.

Resources:

Go Channel Patterns - Wait For Result

b0r — Sun, 12 Dec 2021 19:31:11 +0000

// Detect dark theme var iframe = document.getElementById('tweet-1467962096138825730-406'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1467962096138825730&theme=dark" }

I have decide to record my process of learning how to write more idiomatic code, following Go best practices and design philosophies.

This series of posts will describe channel patterns used for orchestration/signaling in Go via goroutines.

Wait For Result Pattern

The main idea behind Wait For Result pattern is to have:

a channel that provides a signaling semantics
a goroutine that does some work
a goroutine that waits for that work to be done

Example

In this example we have an employee (a goroutine) that has some work to do. We also have a manager (main goroutine) that waits on that work to be done. Once work is done, employee notifies manager by sending a signal (paper) via communication channel ch.

Feel free to try the example on Go Playground

package main


func main() {
    // make channel of type string which provides signaling semantics
    ch := make(chan string)

    // goroutine 'a' that does some work => employee
    go func() {
        // simulate the idea of unknown latency (do not use in production)
        time.Sleep(time.Duration(rand.Intn(500)) * time.Millisecond)
                // when work is done send signal
        ch <- "paper"

        // we don't know the order of print statement
        fmt.Println("employee: sent signal")
    }()

    // goroutine 'main' => manager 
    // goroutines 'main' and 'a' are executed in parallel

    // wait for and receive signal from 'goroutine a'
        // blocking operation
    p := <-ch


    // we don't know which print statement is going to be executed first
    fmt.Println("manager: received signal :", p)

    // ensure enough time to get the result (do not use in production)
    time.Sleep(time.Second)
}

Result (1st execution)

go run main.go
employee: sent signal
manager: received signal : paper

Result (2st execution)

go run main.go
manager: received signal : paper
employee: sent signal

Most common misconceptions:

Note that in the first and the second execution of the previous code, the order of fmt.Println() statement is not guaranteed. Goroutines are executed in parallel.

Conclusion

In this article, wait for result channel pattern was described. In addition, simple implementation was provided.

Readers are encouraged to check out excellent Ardan Labs education materials to learn more.

Resources:

Build Load Balancer in Go

b0r — Wed, 08 Dec 2021 20:30:38 +0000

Learn how to build a simple load balancer server in Go.

Table of Contents:

What is a Load Balancer
Use cases
Load Balancing techniques
Load Balancer implementation
1. Step 1: Create origin server
2. Step 2: Create a load balancer server
Conclusion
Additional information
Resources

What is a Load Balancer

A load balancer is a server that provides a gateway between the client and one or more origin servers. Instead of connecting directly to one of the origin servers, client directs the request to the load balancer server, which routes the request to one of multiple origin servers capable of fulfilling the request.

Load balancing refers to evenly distributing load (incoming network traffic) across a group of backend resources or origin servers. [1]

Load balancer is a type of reverse proxy with capability of evenly distributing the load.

Use cases

Typical use cases are:

distributing client requests or network load efficiently across multiple origin servers
ensuring high availability and reliability by sending requests only to origin servers that are online
providing the flexibility to add or subtract servers as demand dictates (elasticity) [2]

Load Balancing techniques

Random order

Requests are distributed across the group of origin servers at random order.

Round Robin

Requests are distributed across the group of origin servers sequentially.

Weighted Round Robin

Weight (priority) is associated to each origin server based on some metric.
Requests are distributed across the group of origin servers sequentially, respecting the priority of each.

Load/Metric based

Requests are distributed across the group of origin servers based on the load (e.g. affirmed by health check) of each origin server.

IP based

The IP address of the client is used to determine which server receives the request.

Path based

Requests are distributed across the group of origin servers based on the path of the request.

Load Balancer implementation

Step 1: Create origin server

In order to test our load balancer, we first need to create and start a simple origin server.
Origin server will be started twice at port 8081 and 8082, and it will return a string containing the value "origin server response : 8081 or 8082".

package main

import (
    "flag"
    "fmt"
    "log"
    "net/http"
    "time"
)

func main() {
    portFlag := flag.Int("port", 8081, "listening port")
    flag.Parse()
    port := fmt.Sprintf(":%d", *portFlag)

    originServerHandler := http.HandlerFunc(func(rw http.ResponseWriter, req *http.Request) {
        fmt.Printf("[origin server] received request: %s\n", time.Now())
        _, _ = fmt.Fprintf(rw, "origin server response %s", port)
    })

    log.Fatal(http.ListenAndServe(port, originServerHandler))
}

Step 1 Test

Start the server:

go run main -port=8081

go run main -port=8082

Use curl command to validate origin servers (8081, 8082) works as expected:

% curl -i localhost:8081
HTTP/1.1 200 OK
Date: Wed, 08 Dec 2021 20:01:10 GMT
Content-Length: 28
Content-Type: text/plain; charset=utf-8

origin server response :8081%

% curl -i localhost:8082
HTTP/1.1 200 OK
Date: Wed, 08 Dec 2021 20:01:12 GMT
Content-Length: 28
Content-Type: text/plain; charset=utf-8

origin server response :8082

Step 2: Create a load balancer server

package main

import (
    "log"
    "net/http"
    "net/http/httputil"
    "net/url"
    "sync"
)

var nextServerIndex int32 = 0

func main() {
    var mu sync.Mutex

    // define origin server list to load balance the requests
    originServerList := []string{
        "http://localhost:8081",
        "http://localhost:8082",
    }

    loadBalancerHandler := http.HandlerFunc(func(rw http.ResponseWriter, req *http.Request) {
        // use mutex to prevent data race
        mu.Lock()

        // get next server to send a request to
        originServerURL, _ := url.Parse(originServerList[(nextServerIndex)%2])

        // increment next server value
        nextServerIndex++

        mu.Unlock()

        // use existing reverse proxy from httputil to route
        // a request to previously selected server url
        reverseProxy := httputil.NewSingleHostReverseProxy(originServerURL)

        reverseProxy.ServeHTTP(rw, req)
    })

    log.Fatal(http.ListenAndServe(":8080", loadBalancerHandler))
}

Step 2 Test

Start the server:

go run main

Use curl command to validate load balancer works as expected:

First request should be send to origin server :8081

% curl -i localhost:8080
HTTP/1.1 200 OK
Content-Length: 28
Content-Type: text/plain; charset=utf-8
Date: Wed, 08 Dec 2021 20:08:04 GMT

origin server response :8081%

In the terminal of the origin server you should see:

[origin server] received request: 2021-12-08 21:08:09.021995 +0100 CET m=+433.153383251

Second request should be send to the origin server :8082

% curl -i localhost:8080
HTTP/1.1 200 OK
Content-Length: 28
Content-Type: text/plain; charset=utf-8
Date: Wed, 08 Dec 2021 20:08:09 GMT

origin server response :8082%

In the terminal of the origin server you should see:

[origin server] received request: 2021-12-08 21:08:09.402678 +0100 CET m=+423.670045543

Conclusion

In this article, load balancing explanation, its use cases and load balancing techniques were described. In addition, simple implementation of the load balancer server in Go was provided.

Readers are encouraged to try improve this example by implementing another load balancing techniques, add health check or make a list of origin servers dynamic.

Additional information

Resources

[1] https://docs.microsoft.com/en-us/azure/load-balancer/load-balancer-overview
[2] https://www.nginx.com/wp-content/uploads/2014/07/what-is-load-balancing-diagram-NGINX-640x324.png
[3] https://www.nginx.com/resources/glossary/load-balancing/
[cover image] Photo by Wilson Vitorino from Pexels

Build reverse proxy server in Go

b0r — Tue, 07 Dec 2021 20:44:28 +0000

Learn how to build a simple reverse proxy server in Go.

Table of Contents:

What is a Proxy Server
Proxy Server types
1. Forward Proxy
2. Reverse Proxy
Reverse Proxy Implementation
1. Step 1: Create origin server
2. Step 2: Create a reverse proxy server
3. Step 3: Forward a client request to the origin server (via reverse proxy)
4. Step 4: Copy origin server response to the client (via reverse proxy)
Common errors
Conclusion

What is a Proxy Server

Proxy server is a server that provides a gateway between the client (Alice) and the origin server (Bob). Instead of connecting directly to the origin server (to fulfill a resource request), client directs the request to the proxy server, which evaluates the request and performs the required action on origin server on the client behalf (e.g. get current time). [1]

By H2g2bob - Own work, CC0, https://commons.wikimedia.org/w/index.php?curid=16337577

Proxy Server types

Forward Proxy

An ordinary forward proxy is an intermediate server that sits between the client and the origin server. In order to get content from the origin server, the client sends a request to the proxy naming the origin server as the target and the proxy then requests the content from the origin server and returns it to the client. The origin server is only aware of the proxy server and not the client (optional).

Use cases

A typical usage of a forward proxy is to provide Internet access to internal clients that are otherwise restricted by a firewall.
The forward proxy can also use caching to reduce network usage.
In addition, forward proxy can also be used to hide clients IP address. [2]

Reverse Proxy

A reverse proxy, by contrast, appears to the client just like an ordinary web server. No special configuration on the client is necessary. The client makes ordinary requests for content in the name-space of the reverse proxy. The reverse proxy then decides where to send those requests, and returns the content as if it was itself the origin.

Use cases

A typical usage of a reverse proxy is to provide Internet users access to a server that is behind a firewall (opposite of Forward Proxy).

Reverse proxies can also be used to balance load among several back-end servers, or to filter, rate limit or log incoming request, or to provide caching for a slower back-end server.

In addition, reverse proxies can be used simply to bring several servers into the same URL space. [2]

Reverse Proxy Implementation

Step 1: Create origin server

In order to test our reverse proxy, we first need to create and start a simple origin server.
Origin server will be started at port 8081 and it will return a string containing the value "origin server response".



  package main

  import (
    "fmt"
    "log"
    "net/http"
    "time"
  )

    func main() {
      originServerHandler := http.HandlerFunc(func(rw http.ResponseWriter, req *http.Request) {
        fmt.Printf("[origin server] received request at: %s\n", time.Now())
        _, _ = fmt.Fprint(rw, "origin server response")
        })

      log.Fatal(http.ListenAndServe(":8081", originServerHandler))
    }

Step 1 Test

Start the server:



go run main

Use curl command to validate origin server works as expected:



% curl -i localhost:8081
HTTP/1.1 200 OK
Date: Tue, 07 Dec 2021 19:32:00 GMT
Content-Length: 22
Content-Type: text/plain; charset=utf-8

origin server response%

In the terminal of the origin server you should see:



[origin server] received request at: 2021-12-07 20:08:44.302807 +0100 CET m=+518.629994085

Step 2: Create a reverse proxy server



package main

import (
    "fmt"
    "log"
    "net/http"
)

func main() {

    reverseProxy := http.HandlerFunc(func(rw http.ResponseWriter, req *http.Request) {
        fmt.Printf("[reverse proxy server] received request at: %s\n", time.Now())
    })

    log.Fatal(http.ListenAndServe(":8080", reverseProxy))
}

Step 2 Test

Start the server:



go run main

Use curl command to validate reverse proxy works as expected:



% curl -i localhost:8080
HTTP/1.1 200 OK
Date: Tue, 07 Dec 2021 19:17:45 GMT
Content-Length: 0

In the terminal of the reverse proxy server you should see:



[reverse proxy server] received request: 2021-12-07 20:09:44.302807 +0100 CET m=+518.629994085

Step 3: Forward a client request to the origin server (via reverse proxy)

Next, we will update reverse proxy to forward a client request to the origin server. Update main function as follows:



func main() {

  // define origin server URL
    originServerURL, err := url.Parse("http://127.0.0.1:8081")
    if err != nil {
        log.Fatal("invalid origin server URL")
    }

    reverseProxy := http.HandlerFunc(func(rw http.ResponseWriter, req *http.Request) {
        fmt.Printf("[reverse proxy server] received request at: %s\n", time.Now())

    // set req Host, URL and Request URI to forward a request to the origin server
        req.Host = originServerURL.Host
        req.URL.Host = originServerURL.Host
        req.URL.Scheme = originServerURL.Scheme
        req.RequestURI = ""

    // send a request to the origin server
        _, err := http.DefaultClient.Do(req)
        if err != nil {
            rw.WriteHeader(http.StatusInternalServerError)
            _, _ = fmt.Fprint(rw, err)
            return
        }
    })

    log.Fatal(http.ListenAndServe(":8080", reverseProxy))
}

Step 3 Test

Start the server:



go run main

Use curl command to validate reverse proxy works as expected:



% curl -i localhost:8080
HTTP/1.1 200 OK
Date: Tue, 07 Dec 2021 19:35:19 GMT
Content-Length: 0

In the terminal of the reverse proxy server you should see:



[reverse proxy server] received request at: 2021-12-07 20:37:30.288783 +0100 CET m=+4.150788001

In the terminal of the origin server you should see:



received request: 2021-12-07 20:37:30.290371 +0100 CET m=+97.775715418

Step 4: Copy Origin Server Response

Once we were able to proxy a client response to the origin server, we need to get the response from the origin server back to the client. To do that, update the main function as follows:




    func main() {

    // define origin server URL
    originServerURL, err := url.Parse("http://127.0.0.1:8081")
    if err != nil {
        log.Fatal("invalid origin server URL")
    }

    reverseProxy := http.HandlerFunc(func(rw http.ResponseWriter, req *http.Request) {
        fmt.Printf("[reverse proxy server] received request at: %s\n", time.Now())

        // set req Host, URL and Request URI to forward a request to the origin server
        req.Host = originServerURL.Host
        req.URL.Host = originServerURL.Host
        req.URL.Scheme = originServerURL.Scheme
        req.RequestURI = ""

      // save the response from the origin server
        originServerResponse, err := http.DefaultClient.Do(req)
        if err != nil {
            rw.WriteHeader(http.StatusInternalServerError)
            _, _ = fmt.Fprint(rw, err)
            return
        }

      // return response to the client
        rw.WriteHeader(http.StatusOK)
        io.Copy(rw, originServerResponse.Body)
    })

    log.Fatal(http.ListenAndServe(":8080", reverseProxy))

Step 4 Test

Start the server:



go run main

Use curl command to validate reverse proxy works as expected:



% curl -i localhost:8080
HTTP/1.1 200 OK
Date: Tue, 07 Dec 2021 19:42:07 GMT
Content-Length: 22
Content-Type: text/plain; charset=utf-8

origin server response%

In the terminal of the reverse proxy server you should see:



[reverse proxy server] received request at: 2021-12-07 20:42:07.654365 +0100 CET m=+5.612744376

In the terminal of the origin server you should see:



received request: 2021-12-07 20:42:07.657175 +0100 CET m=+375.150991460

Common errors

Request.RequestURI can't be set in client request

If the request is executed to the http://localhost:8080/what-is-this the RequestURI value will be what-is-this.

According to Go docs ../src/net/http/client.go:217, requestURI should always be set to "" before trying to send a request.

Conclusion

In this article, reverse proxy explanation and its use cases were described. In addition, simple implementation of the reverse proxy in Go was provided.

Readers are encouraged to try improve this example by implementing copying of the response headers, adding X-Forwarded-For header and to implement HTTP2 support.

Also, don't forget to watch this awesome talk FOSDEM 2019: How to write a reverse proxy with Go in 25 minutes. by Julien Salleyron on YT.

Resources:

[1] https://en.wikipedia.org/wiki/Proxy_server#cite_note-apache-forward-reverse-5
[2] https://httpd.apache.org/docs/2.0/mod/mod_proxy.html#forwardreverse
[3] Photo by Clayton on Unsplash