Go Basics Training – Standard Library

Docs: Input/Output

Mon, 01 Jan 0001 00:00:00 +0000

Basics

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


package main

import (
 "fmt"
 "log"
 "os"
)

func main() {
 const filename = "/tmp/file.txt"

 err := os.WriteFile(filename, []byte("Hello, file system\n"), 0644)
 if err != nil {
 log.Fatal(err)
 }

 content, err := os.ReadFile(filename)
 if err != nil {
 log.Fatal(err)
 }

 fmt.Printf("%s", content)
}

Output:
Hello, file system

Reader/Writer

The above example of reading a file loads the whole file into memory. This can cause problems when we are dealing with large files. To solve this problem, we can load chunks of data and place them into a buffer.

The Go standard library provides the Reader and Writer interface for reading and writing data in a streaming fashion. The various reader and writer implementations are then often used together with the primitives from the io package (e.g. io.Copy ).

The io.Writer interface expects a slice of bytes and returns the amount of bytes that were written and an error.

type Writer interface {
 Write(p []byte) (n int, err error)
}

The io.Reader interface expects an byte slice. This slice is used as a buffer. It returns the amount of bytes that were read and an error.

type Reader interface {
 Read(p []byte) (n int, err error)
}

Here is an example were we copy data from a bytes.Buffer to a file (os.File ). We create the buffer from a string using bytes.NewBufferString . Then we open the file with os.Create . With io.Copy we copy all bytes from the buffer to the file.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


package main

import (
 "bytes"
 "fmt"
 "io"
 "os"
)

func main() {
 // buffer implements io.Reader and is our source
 buffer := bytes.NewBufferString("Some file content")

 // file implements io.Writer and is our destination
 file, err := os.Create("./io.txt")
 if err != nil {
 fmt.Println(err)
 os.Exit(1)
 }
 defer file.Close()

 // reades bytes from buffer and writes them to file
 n, err := io.Copy(file, buffer)
 fmt.Printf("%d bytes written\n", n)
}

Output:
17 bytes written

Docs: JSON

Mon, 01 Jan 0001 00:00:00 +0000

Encoding

Go allows us to encode structs to json by using json.Marshal .

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


package main

import (
 "encoding/json"
 "fmt"
 "os"
)

type User struct {
 Name string
 FullName string
 Followers int
}

func main() {
 user := User{
 Name: "Alice",
 FullName: "Alice Nyffenegger",
 Followers: 44,
 }

 output, err := json.Marshal(user)
 if err != nil {
 fmt.Println(err)
 os.Exit(1)
 }
 fmt.Printf("%s\n", output)
}

Output:
{"Name":"Alice","FullName":"Alice Nyffenegger","Followers":44}

Note

Other packages (e.g. json ) cannot access the struct fields if they are lower case. Be sure to make them public by upper casing the first letter.

Decoding

Decoding works similiarly with the json.Unmarshal function. In addition to the JSON data (as a byte slice []byte) we also pass a pointer to the struct itself. Since we use a pointer the struct can be modified directly and is not returned by Unmarshal.

With backticks we can create multiline strings or strings which contain a lot of quotes (") like JSON data.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


package main

import (
 "encoding/json"
 "fmt"
 "os"
)

type User struct {
 Name string `json:"short_name"`
 FullName string `json:"name"`
 Followers int `json:"followers"`
}

func main() {
 input := `{"short_name":"Alice","name":"Alice Nyffenegger","followers":44}`

 user := User{}

 err := json.Unmarshal([]byte(input), &user)
 if err != nil {
 fmt.Println(err)
 os.Exit(1)
 }
 fmt.Printf("%s %s %d\n", user.Name, user.FullName, user.Followers)
}

Output:
Alice Alice Nyffenegger 44

Docs: HTTP Client

Mon, 01 Jan 0001 00:00:00 +0000

The Go standard library offers a HTTP package which provides a server and a client. In the following sections we learn how we can use the HTTP client.

Quick start

The following example shows how we can perform a GET request and print the body to the standard output.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


package main

import (
 "fmt"
 "io"
 "net/http"
 "os"
)

func main() {
 resp, err := http.Get("https://google.com")
 if err != nil {
 fmt.Fprintln(os.Stderr, err)
 os.Exit(1)
 }
 _, err = io.Copy(os.Stdout, resp.Body)
 if err != nil {
 fmt.Fprintln(os.Stderr, err)
 os.Exit(1)
 }
}

The function http.Get returns a http.Response . The response contains the field Body which is an io.Reader from which we can read the response.

http.Client

The shortcut functions like http.Get and http.Post are convenient but in most of the cases we want more control over our requests (e.g. set a request timeout).

Usually we create our own http.Client with appropriate settings. You should always set a Timeout otherwise, if a request is blocked it will hang forever. We can use a single HTTP client instance throughout our whole application as it is safe for concurrent use. The client then manages a connection pool for us and we benefit from reusing connections if we do multilple requests to the same host.

We can then use the Get method on our http client::

client = &http.Client{
 Timeout: time.Second * 30,
}

resp, err := client.Get("https://google.com")

Set Headers

To set headers on a request we create a new http.Request with http.NewRequest .

req, err := http.NewRequest("GET", "http://localhost:8080", nil)

req.Header.Set("Authorization", "Bearer: my-super-secret-token")

resp, err := client.Do(req)

Send Content

To send content in the body of a POST request we pass a io.Reader to the NewRequest function. The reader could for example be an open file or a buffer. In the following example we create a bytes.Buffer from a string.

body := bytes.NewBufferString("body content")

req, err := http.NewRequest("POST", "http://localhost:8080", body)
if err != nil {
 return err
}

req.Header.Set("Content-Type", "text/plain")

resp, err := client.Do(req)

Send JSON

Often we want to send a struct serialized as JSON to an endpoint. The following example sends {"name":"execute"} as payload.

type action struct {
 Name string `json:"name"`
}

executeAction := &action{
 Name: "execute",
}

payload, err := json.Marshal(executeAction)
if err != nil {
 return err
}

req, err := http.NewRequest("POST", "http://localhost:8080/run", bytes.NewBuffer(payload))
if err != nil {
 return err
}

req.Header.Set("Content-Type", "application/json")

resp, err := client.Do(req)

Receive JSON

client := &http.Client{
 Timeout: time.Second * 20,
}

type action struct {
 Name string `json:"name"`
}

req, err := http.NewRequest("POST", "http://localhost:8080/run", nil)
if err != nil {
 return err
}

resp, err := client.Do(req)
if err != nil {
 return err
}

if resp.StatusCode > 399 {
 return fmt.Errorf("http status code %d", resp.StatusCode)
}

// we wrap the resp.Body reader in a io.LimitReader to avoid a crash if the server sends too much content
data, err := io.ReadAll(io.LimitReader(resp.Body, 1000))

// initialize an action
a := action{}

// deserialize data into a
err = json.Unmarshal(data, &a)

fmt.Println("action", a.Name)

Docs: HTTP Server

Mon, 01 Jan 0001 00:00:00 +0000

Quick start

Go allows us to start a simple HTTP server with minimal code:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


package main

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

func helloHandler(w http.ResponseWriter, r *http.Request) {
 fmt.Fprintln(w, "Hello World")
}

func main() {
 http.HandleFunc("/hello", helloHandler)

 err := http.ListenAndServe(":8080", nil)
 if err != nil {
 fmt.Println(err)
 os.Exit(1)
 }
}

Now you can access http://localhost:8080/hello .

http.Handler

The http.Handler interface is the basic building block of all HTTP servers.

type Handler interface {
 ServeHTTP(ResponseWriter, *Request)
}

The ServeHTTP method has two parameters:

http.ResponseWriter is an interface with the following methods:
- Header() returns all headers and allows setting new ones.
- WriteHeader(statusCode int) allows setting a status code for the response. It must be called before Write() and defaults to http.StatusOK if not set. For a full list of status codes see the documentation .
- Write() allows us to use all functions that expect an io.Writer interface (e.g. fmt.Fprint or io.WriteString )
http.Request defines the request parameters. Example:
- Method: GET, POST, PUT etc.
- Header: request headers
- Body: request body (typically used with POST requests)
- Form: form values

So a minimal handler would look like this:

type myHandler struct{}

func (h *myHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 fmt.Fprintln(w, "hello")
}

With the function http.HandlerFunc we can transform a function with the following signature into a http.Handler.

func myHandlerFunc(w http.ResponseWriter, r *http.Request) {
fmt.Fprintln(w, "hello")
}
handler := http.HandlerFunc(myHandlerFunc)

`http.ResponseWriter`

The following is an example how to use http.ResponseWriter:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


package main

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

func helloHandler(w http.ResponseWriter, r *http.Request) {
 // set content type header
 w.Header().Set("Content-Type", "text/plain")

 // set status header (400)
 w.WriteHeader(http.StatusBadRequest)

 // respond with an error message
 // `fmt.Fprint` expects an `io.Writer` interface
 fmt.Fprint(w, "invalid request")
}

func main() {
 http.HandleFunc("/hello", helloHandler)

 // ListenAndServe always returns a non-nil error.
 err := http.ListenAndServe(":8080", nil)
 if err != nil {
 fmt.Println(err)
 os.Exit(1)
 }
}

`http.Request`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


package main

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

func helloHandler(w http.ResponseWriter, r *http.Request) {
 fmt.Fprintln(w, "Method: ", r.Method)
 fmt.Fprintln(w, "URL: ", r.URL)
 fmt.Fprintln(w, "Proto: ", r.Proto)
 fmt.Fprintln(w, "Header: ", r.Header)
 fmt.Fprintln(w, "Body: ", r.Body)
 fmt.Fprintln(w, "ContentLength: ", r.ContentLength)
 fmt.Fprintln(w, "Form: ", r.Form)
 fmt.Fprintln(w, "RemoteAddr: ", r.RemoteAddr)
}

func main() {
 http.HandleFunc("/hello", helloHandler)

 // ListenAndServe always returns a non-nil error.
 err := http.ListenAndServe(":8080", nil)
 if err != nil {
 fmt.Println(err)
 os.Exit(1)
 }
}

Receive Data

The field Body in the http.Request implements io.Reader . We can use functions that expect an io.Reader like io.ReadAll to read the body.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


package main

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

func echoHandler(w http.ResponseWriter, r *http.Request) {
 body, err := io.ReadAll(r.Body)
 if err != nil {
 w.WriteHeader(http.StatusBadRequest)
 return
 }
 w.Write(body)
}

func main() {
 http.HandleFunc("/echo", echoHandler)

 // ListenAndServe always returns a non-nil error.
 log.Fatal(http.ListenAndServe(":8080", nil))
}

Try sending a request with curl:

curl -d 'body' http://localhost:8080/hello

Middeware

A common pattern is to wrap one handler within another handler. This could for example be used for logging or authentication. For this we pass our actual handler (inner handler) to the middleware.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


package main

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

func secretHandler() http.HandlerFunc {
 return func(w http.ResponseWriter, r *http.Request) {
 fmt.Fprintln(w, "top secret")
 }
}

func authMiddleware(next http.Handler) http.HandlerFunc {
 return func(w http.ResponseWriter, r *http.Request) {
 user, password, _ := r.BasicAuth()
 if !(user == "admin" && password == "secret") {
 code := http.StatusUnauthorized
 http.Error(w, http.StatusText(code), code)
 return
 }
 next.ServeHTTP(w, r)
 }
}

func main() {
 http.Handle("/secret", authMiddleware(secretHandler()))

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

Docs: Date and Time

Mon, 01 Jan 0001 00:00:00 +0000

Basics

Time is represented with the time.Time struct.

The output in the examples below is generated by the Go playground . The Go playground uses a static time to achieve optimal caching performance.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


package main

import (
 "fmt"
 "time"
)

func main() {
 time := time.Now()
 fmt.Println(time)
}

Output:
2009-11-10 23:00:00 +0000 UTC m=+0.000000001

Parsing

To parse a string to time.Time we use time.Parse . Other programming languages often use “format strings” that look something like: yyyy-MM-dd HH:mm:ss. Go does things differently and uses a reference time.

Jan 2 15:04:05 2006 MST

An easy way to remember this value is that it holds, when presented in this order, the values (lined up with the elements above):

 1 2 3 4 5 6 -7

Every layout string is a representation of this time stamp. If you want to format a date differently, you must rewrite the above date.

Example:

Mon Jan 2 15:04:05 MST 2006

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


package main

import (
 "fmt"
 "log"
 "time"
)

func main() {
 t, err := time.Parse("Mon Jan 2 15:04:05 MST 2006", "Thu Feb 25 11:06:39 PST 2021")
 if err != nil {
 log.Fatal(err)
 }
 fmt.Println(t)
 fmt.Println(t.Weekday())
}

Output:
2021-02-25 11:06:39 +0000 PST
Thursday

Comparing dates

Dates can be compared with time.Before and time.After

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


package main

import (
 "fmt"
 "time"
)

func main() {
 year2000 := time.Date(2000, 1, 1, 0, 0, 0, 0, time.UTC)
 year3000 := time.Date(3000, 1, 1, 0, 0, 0, 0, time.UTC)

 isYear3000AfterYear2000 := year3000.After(year2000) // True
 isYear2000AfterYear3000 := year2000.After(year3000) // False

 fmt.Printf("year3000.After(year2000) = %v\n", isYear3000AfterYear2000)
 fmt.Printf("year2000.After(year3000) = %v\n", isYear2000AfterYear3000)

}

Output:
year3000.After(year2000) = true
year2000.After(year3000) = false

Duration

A time.Duration represents the time between two instants.

To get a duration we can subtract two dates:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


package main

import (
 "fmt"
 "time"
)

func expensiveCall() {
 time.Sleep(10 * time.Second)
}

func main() {
 t0 := time.Now()
 expensiveCall()
 t1 := time.Now()
 duration := t1.Sub(t0)
 fmt.Printf("The call took %v to run.\n", duration)
}

Output:
The call took 10s to run.

Go Basics Training – Standard Library

Docs: Input/Output

Basics

Reader/Writer

Docs: JSON

Encoding

Note

Tags

Decoding

Docs: HTTP Client

Quick start

http.Client

Set Headers

Send Content

Send JSON

Receive JSON

Docs: HTTP Server

Quick start

http.Handler

http.ResponseWriter

http.Request

Receive Data

Middeware

Docs: Date and Time

Basics

Parsing

Comparing dates

Duration

`http.ResponseWriter`

`http.Request`