Forem: Bryan Primus Lumbantobing

Graceful Shutdown in Go

Bryan Primus Lumbantobing — Fri, 13 Feb 2026 05:43:46 +0000

This is cross-post from my blog: https://bryanprim.us/blogs/graceful-shutdown-in-go

Visit original post for better reading experience where mermaid diagram properly rendered

TL;DR

http.Server.ListenAndServe is a blocking call, so if we run it in main nothing after it runs.
Start the server in a goroutine and keep main free for handling shutdown.
Send any server startup errors to a channel so main can handle them.
Listen for SIGINT (Ctrl+C) and SIGTERM (container orchestration) using signal.NotifyContext.
Use select to wait on multiple channels: shutdown signal and server error channel.
On shutdown signal, create a deadline with context.WithTimeout and call server.Shutdown(ctx) to stop accepting new requests while letting in flight requests finish.
Clean up resources like DB connections after shutdown completes.
Use sync.WaitGroup to wait for other background goroutines to finish gracefully. (TODO)
Bonus: Migrate to errgroup for better orchestration and automatic context cancellation across goroutines. (TODO)

Example Scenario

Imagine we are eating at a restaurant. We still haven't finished our food. The restaurant is about to close. The restaurant would stop taking new orders or seating new customers, and a good restaurant will usually wait for us to finish our food before closing and cleaning up. That's exactly what a graceful shutdown is. We are trying to become a good restaurant. Even so, a good restaurant won't wait forever. It sets a time limit. If we exceed it, we'll be asked to leave.

In a typical web service using HTTP, we first stop accepting new incoming requests, then wait for in flight requests to finish within a time limit. We don't want to wait forever, of course. Once all requests have completed (or the deadline has passed), we can safely shut down the server and clean up resources such as closing DB connections and stopping any other background work.

flowchart TB
  %% Graceful shutdown
  subgraph G[Graceful shutdown]
    direction TB
    subgraph GR[Restaurant]
      direction TB
      r1[Normal service]
      r2[Closing time approaching]
      r3[Stop seating new customers]
      r4[Stop taking new orders]
      r5[Let current diners finish eating]
      r6{Time limit reached?}
      r7[Ask remaining diners to leave]
      r8[Clean up and close]
      r1 --> r2 --> r3 --> r4 --> r5 --> r6
      r6 -- No --> r5
      r6 -- Yes --> r7 --> r8
    end
    subgraph GS[Web service]
      direction TB
      s1[Normal traffic]
      s2[Shutdown signal received]
      s3[Stop accepting new incoming HTTP requests]
      s4[Drain in flight requests]
      s5{Shutdown timeout reached?}
      s6[Force close remaining work]
      s7[Clean up resources]
      s8[Close DB connections]
      s9[Stop background operations]
      s1 --> s2 --> s3 --> s4 --> s5
      s5 -- No --> s4
      s5 -- Yes --> s6 --> s7 --> s8 --> s9
    end
  end

The opposite of this would be a forceful shutdown, where the restaurant immediately kicks customers out even though they haven't finished their food, interrupts orders being prepared in the kitchen, and starts cleaning up, mopping the floor and stacking chairs, while customers still need them.

flowchart TB
  %% Forceful shutdown
  subgraph F[Forceful shutdown]
    direction TB
    subgraph FR[Restaurant]
      direction TB
      fr1[Closing time approaching]
      fr2[Kick customers out immediately]
      fr3[Start cleaning now]
      fr4[Orders in kitchen get interrupted]
      fr1 --> fr2 --> fr3
      fr2 --> fr4
    end
    subgraph FS[Web service]
      direction TB
      fs1[Shutdown signal received]
      fs2[Immediately stop service]
      fs3[Drop active requests]
      fs4[Close connections now]
      fs5[Best effort cleanup]
      fs1 --> fs2 --> fs3 --> fs4 --> fs5
    end
  end

HTTP Server in Go

Go provides the net/http package that we can use to run an HTTP server using the server.ListenAndServe() method. This method is a blocking operation. It contains a never ending loop that waits for and serves each new connection or request. That's why any code placed after this call will never execute.

func (srv *Server) Serve(l net.Listener) error {
    // ... setup ...
    for {  // <-- An infinite loop!
        rw, err := l.Accept()  // <-- THIS IS THE KEY BLOCKING CALL!
        if err != nil {
            // ... error handling ...
        }
        c := srv.newConn(rw)
        go c.serve(connCtx)  // Handle each connection in a new goroutine
    }
}

It blocks because it's an infinite loop with a blocking syscall (Accept()), not because of channels. It's the same reason any infinite loop blocks. The function literally never returns unless there's an error!

Moving to a Background Goroutine

We just learned that server.ListenAndServe() in Go is a blocking operation. Running it directly in the main function (which is the main goroutine) is a very bad idea because:

We won't be able to run code after it.
We won't be able to listen for external signals for graceful shutdown.
We won't be able to run background workers or other concurrent tasks.
Our deferred cleanup functions won't execute until the server stops (which may never happen in normal operation).

func main() {
    defer cleanup() // This NEVER runs (unless server errors out)
    log.Println("Starting server...")
    // This blocks forever!
    server.ListenAndServe()
    // NONE of this code ever executes:
    log.Println("Server stopped") // Never prints
    startBackgroundWorker()       // Never runs
    listenForShutdownSignals()    // Never runs
}

Therefore, the best practice is to run it in a background goroutine. This unblocks the main goroutine so we can run other operations such as handling shutdown.

func main() {
    go func() {
        // This still blocks forever!
        // But now in the scope of its own background goroutine
        err := server.ListenAndServe()
        if err != nil {
            log.Fatal(err)
        }
    }()
    // -- Code after this will execute --
}

Communicating with Channels

Moving server.ListenAndServe to a background goroutine means the main goroutine never sees any error it returns. If the server fails to start, we usually want the whole program to exit right away, so anything that comes after it should never run.

We need a way to communicate between goroutines: the background goroutine running the server, and the main goroutine. We can accomplish this using channels. A channel is a thread safe queue. Values come out in the same order they went in. We can send values from any number of goroutines and receive them from any number of other goroutines without corrupted data or a race condition.

First, we create a channel to carry our server error in the main goroutine.

func main() {
    serverErrors := make(chan error, 1)
}

Then we send a value to that channel from our background goroutine using the <- syntax.

func main() {
    go func() {
        err := server.ListenAndServe()
        if err != nil {
            serverErrors <- err
        }
    }()
}

Now we introduce a channel receive that waits for a value to arrive. A channel receive is a blocking operation as well, which means the code after it won't execute until a value is received. We can then use that error to exit the program early.

func main() {
    // Creating a channel
    serverErrors := make(chan error, 1)
    go func() {
        err := server.ListenAndServe()
        if err != nil {
            // Send error to the channel
            serverErrors <- err
        }
    }()
    // Receiving from the channel
    // This will block the main goroutine
    serverError := <-serverErrors
    // This will not execute until we receive a server error
    fmt.Println("Blocked unless there is a server error")
    if serverError != nil {
        log.Println("Program killed:", serverError)
    }
}

The buffered channel with capacity 1 (make(chan error, 1)) allows the goroutine to send one error without blocking, even if no receiver is ready yet. This prevents a potential deadlock if the server fails to start immediately, ensuring the error can be sent before the main goroutine reaches the receive statement.

Understanding Context

Before we listen for shutdown signals, let's understand Go's context package. It's central to how graceful shutdown works.

Imagine ordering food on an app and then cancelling the order. Without context, the kitchen keeps cooking, a driver gets assigned, and the whole chain keeps going even though we cancelled. Context is how we tell the whole chain "stop, the user cancelled."

The equivalent use cases in our program are timeouts and cancellation. For example, a slow database query that might take 30 seconds when we want to give up after 5. Or a client (say, a web browser) that closes the connection before receiving the response. In that case, we might want to cancel expensive internal operations on the server to save resources. Context can also carry request scoped values through the call chain, such as a requestId or userId for each HTTP handler.

When a context is cancelled or reaches its timeout, we are notified through ctx.Done(), which returns a channel that closes when the context is done. Receiving from it (<-ctx.Done()) is a blocking operation that waits until one of those events occurs.

Listening for Shutdown Signals

Now that server.ListenAndServe() no longer blocks the main goroutine, we can handle graceful shutdown. SIGTERM is the polite "please shut down" signal that the OS or orchestrator sends before it gets impatient and sends SIGKILL, which forcibly kills the program. For example, Kubernetes sends SIGTERM to a pod and waits for terminationGracePeriodSeconds (30 seconds by default) before sending SIGKILL. For local development, we'll also listen for SIGINT, triggered by pressing Ctrl+C in the terminal.

We use signal.NotifyContext to create a context that is automatically cancelled when one of our specified signals is received.

func main() {
    ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
    defer stop()
}

defer stop() resets the signal behavior back to the default after we're done handling shutdown. This is important because if a second signal arrives during our graceful shutdown process, we want the program to terminate immediately rather than being caught by our handler again.

This root context can also be passed to dependent resources so they are aware of application level cancellation.

func main() {
    ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
    defer stop()
    // db pool example using pgx driver
    db, err := pgxpool.New(ctx, "postgres://postgres:password@localhost:5432/mydb")
    // background goroutine if any
    go processQueue(ctx)
}

Waiting on Multiple Channels with Select

We now have two channels to wait on: ctx.Done() for the shutdown signal, and serverErrors for a server startup failure. We can't just receive from one because either event could happen first. This is exactly what Go's select statement is for.

select works like a switch but for channel operations. It blocks until one of its cases can proceed, then executes that case.

select {
case err := <-serverErrors:
    // The server failed to start or crashed
    log.Println("Server error:", err)
    return
case <-ctx.Done():
    // We received a shutdown signal (SIGINT or SIGTERM)
    log.Println("Shutdown signal received")
}

If the server fails to start (e.g., port already in use), the first case fires and we exit immediately. If the server starts successfully and we later press Ctrl+C or the orchestrator sends SIGTERM, the second case fires and we begin graceful shutdown.

Shutting Down the Server

When the shutdown signal arrives, we need to tell the server to stop accepting new connections and wait for in flight requests to finish. This is what server.Shutdown(ctx) does. We pass it a context with a timeout to set a deadline. We don't want to wait forever for slow requests.

case <-ctx.Done():
    log.Println("Shutdown signal received")
    shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()
    err := server.Shutdown(shutdownCtx)
    if err != nil {
        log.Println("Graceful shutdown failed:", err)
    }

There are a few important details here:

We create a new context with context.Background() rather than reusing ctx, because ctx is already cancelled (that's how we got here). The new timeout gives in flight requests up to 10 seconds to complete.
server.Shutdown closes the listeners, then waits for all active connections to become idle. If the timeout expires before that happens, Shutdown returns context.DeadlineExceeded and any remaining connections are abandoned. The server did its best, but some requests may be cut off.
When Shutdown is called, the ListenAndServe call in our background goroutine returns http.ErrServerClosed. This is expected during graceful shutdown and is not a real error. We need to filter it in our goroutine so it doesn't get sent to serverErrors:

go func() {
    err := server.ListenAndServe()
    if err != nil && !errors.Is(err, http.ErrServerClosed) {
        serverErrors <- err
    }
}()

Without this filter, serverErrors would receive a value on every graceful shutdown, making it look like the server crashed.

Cleaning Up Resources

After the server has shut down, we can safely clean up resources like database connections. The simplest way to do this in Go is with defer statements, which execute in LIFO (last in, first out) order when the function returns.

func main() {
    // ... setup ...
    db, err := pgxpool.New(ctx, connStr)
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close() // Runs when main returns, after shutdown completes
    // ... server start, select, shutdown ...
}

Because defer runs when main returns, and our select + Shutdown sequence happens before that return, we can be confident the DB pool is closed only after the server has finished processing all requests.

Putting It All Together

Here is the complete implementation combining everything we've covered: starting the server in a background goroutine, communicating errors via a channel, listening for shutdown signals with context, using select to wait on both, shutting down the server with a timeout, and cleaning up resources.

package main
import (
    "context"
    "errors"
    "log"
    "net/http"
    "os"
    "os/signal"
    "syscall"
    "time"
    "github.com/jackc/pgx/v5/pgxpool"
)
func main() {
    // ---------------------------------------------------------------
    // Create a context that is cancelled on SIGINT or SIGTERM.
    // ---------------------------------------------------------------
    ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
    defer stop()
    // ---------------------------------------------------------------
    // Connect to the database.
    // ---------------------------------------------------------------
    db, err := pgxpool.New(ctx, os.Getenv("DATABASE_URL"))
    if err != nil {
        log.Println("Unable to create connection pool:", err)
        return
    }
    defer db.Close()
    log.Println("Connected to database")
    // ---------------------------------------------------------------
    // Register routes.
    // ---------------------------------------------------------------
    http.HandleFunc("/slow", func(w http.ResponseWriter, r *http.Request) {
        log.Println("Slow request started")
        time.Sleep(5 * time.Second)
        w.Write([]byte("done"))
        log.Println("Slow request finished")
    })

    // ---------------------------------------------------------------
    // Set up the server.
    // ---------------------------------------------------------------
    server := &http.Server{
        Addr:         ":8080",
        Handler:      http.DefaultServeMux,
        ReadTimeout:  10 * time.Second,
        WriteTimeout: 30 * time.Second,
        IdleTimeout:  60 * time.Second,
    }
    // ---------------------------------------------------------------
    // Start the server in a background goroutine.
    // Send any unexpected error to the channel.
    // ---------------------------------------------------------------
    serverErrors := make(chan error, 1)
    go func() {
        log.Println("Server listening on", server.Addr)
        err := server.ListenAndServe()
        // http.ErrServerClosed is expected when Shutdown is called.
        if err != nil && !errors.Is(err, http.ErrServerClosed) {
            serverErrors <- err
        }
    }()
    // ---------------------------------------------------------------
    // Block until we receive a shutdown signal or a server error.
    // ---------------------------------------------------------------
    select {
    case err := <-serverErrors:
        log.Println("Server error:", err)
        return
    case <-ctx.Done():
        stop() // Reset signal behavior so a second signal exits immediately.
        log.Println("Shutdown signal received, draining requests...")
        // Give in flight requests a deadline to complete.
        shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
        defer cancel()
        err := server.Shutdown(shutdownCtx)
        if err != nil {
            log.Println("Graceful shutdown failed:", err)
            return
        }
        log.Println("Server shut down gracefully")
    }
    // ---------------------------------------------------------------
    // At this point, deferred functions run:
    // - db.Close() closes the connection pool
    // - stop() resets signal handling
    // ---------------------------------------------------------------
}

Testing It Manually

Let's prove that this actually works. The idea is simple: register a slow endpoint, start the server, send a request to that endpoint, and hit Ctrl+C while the request is still being processed. If graceful shutdown is working, the server should wait for the request to finish before exiting.

Step 1: Notice the slow endpoint.

In the code above, we registered a /slow handler that takes 5 seconds to respond. This gives us a window to send the shutdown signal while the request is in flight.

Step 2: Start the server.

go run main.go

We should see something like:

Connected to database
Server listening on :8080

Step 3: Send a request to the slow endpoint.

Open a second terminal and run:

curl http://localhost:8080/slow

This will hang for 5 seconds while the server processes the request.

Step 4: Send the shutdown signal.

Go back to the first terminal (where the server is running) and press Ctrl+C while the curl request is still waiting. We should see something like:

Slow request started
Shutdown signal received, draining requests...
Slow request finished
Server shut down gracefully

Notice the order. The shutdown signal was received, but the server waited for the slow request to finish before shutting down. The curl request in the second terminal should return done with no error.

What happens without graceful shutdown?

If we were to just kill the process (e.g., kill -9 or no shutdown handling at all), the curl request would fail with something like curl: (52) Empty reply from server because the connection gets dropped mid response.

What happens if the request exceeds the shutdown timeout?

Try changing the sleep to 15 seconds (longer than our 10 second shutdown timeout). When we press Ctrl+C, we'll see:

Slow request started
Shutdown signal received, draining requests...
Graceful shutdown failed: context deadline exceeded

The server gave up waiting after 10 seconds and exited. The curl request will fail because the connection was closed before the response was sent. This is the timeout acting as a safety net so the server never hangs forever waiting for a stuck request.

Wrapping Up

That covers the core of graceful shutdown in Go. To recap what we built: we moved the server out of the main goroutine so it doesn't block everything, used a channel to catch startup errors, listened for OS signals through context, and used select to react to whichever event comes first. When a shutdown signal arrives, we give in flight requests time to finish before cleaning up resources like the database connection.

This is a solid foundation for any Go service. In a future post, we'll take it further with sync.WaitGroup for waiting on background goroutines, and then refactor the whole thing using errgroup for cleaner orchestration.

Using SSH to Connect Local Git to Remote Repositories

Bryan Primus Lumbantobing — Sat, 09 Nov 2024 08:40:30 +0000

This is cross-post from my blog: https://www.bryanprim.us/blogs/using-ssh-to-connect-local-git-to-remote-repositories

Visit original post for better reading experience where mermaid diagram properly rendered

TL;DR

SSH uses a public and private key pair instead of tokens, making it more secure and convenient for Git authentication.
Generate keys with ssh-keygen -t ed25519, then add the public key to our remote repository platform (GitHub, GitLab, Bitbucket).
Use ssh-agent and an SSH config file with AddKeysToAgent and UseKeychain so we only enter our passphrase once.
Test the connection with ssh -T git@github.com to verify everything is working.

GitHub, GitLab, Bitbucket and many more are platforms to host remote repositories using Git.
The two most common ways to connect to a remote repository from local Git are HTTPS and SSH.

Each has its own advantages and disadvantages, but throughout this blog post we will focus on SSH since it is the most commonly used method and it offers many benefits compared to HTTPS.

Note: This post assumes git is installed on the local machine. It can also be used as a practical guide for setting up a new SSH connection to a remote repository. With existing SSH keys, jump straight to Generating SSH Keys.

SSH and Git

SSH is a protocol that allows us to securely communicate between a local machine and a remote host. Git is a distributed version control system designed to track changes in files and directories over time.

Git is a collaboration tool that allows us to work on projects collaboratively, and using SSH will help us communicate our changes to other people in a secure way.

Benefits of Using SSH over HTTPS

Security

When using HTTPS to connect to a remote repository, we typically use a Personal Access Token (PAT) for authentication. Platforms like GitHub deprecated password based HTTPS authentication back in 2021, so tokens are now the standard. The token and data are encrypted in transit, so they’re not easily readable by anyone on the network. However, we still need to enter or cache our token for each session, and if the token is leaked or stolen, anyone with it can access our repositories until we revoke it.

When using SSH, we use a private and public key pair for authentication, which works differently:

Private Key is stored only on our local machine. Think of it as a digital signature unique to us. It is encrypted and often secured with a passphrase.
Public Key is stored on the remote server. This is what our private key "unlocks" to prove it is really us.

sequenceDiagram
    participant Local as Our Machine
    participant Server as Remote Server
    Local->>Server: Connection request
    Server->>Local: Send challenge (newly generated)
    Note over Local: Solve challenge using Private Key
    Local->>Server: Send response
    Note over Server: Verify response using Public Key
    Server->>Local: Authenticated

Our local machine uses the private key to prove our identity without sending the private key itself over the network. Instead, the server sends a challenge to our local machine that only our private key can solve. This challenge is newly generated every time we try to connect to the remote server. After our machine solves the challenge, the server verifies the response using our public key. If it matches, we are authenticated. Because the challenge changes every time, intercepting the network traffic won't help an attacker gain access.

Convenience

Using SSH is more convenient than HTTPS for connecting to a remote server because it eliminates the need to enter our token every time. Instead, we can use an SSH agent, which securely stores our passphrase in memory and handles the authentication process for subsequent connections.

Generate SSH Keys

There are several algorithms that can be used to generate SSH keys. In this blog post, we will use Ed25519 (Edwards-curve Digital Signature Algorithm) because it is modern and faster than other algorithms.

Check Existing SSH Keys

Before generating a new SSH key, we should check if we already have one because we don't want to accidentally overwrite an existing key.

### input
ls -al ~/.ssh

Look for id_ed25519 and id_ed25519.pub as these are the default file names for SSH key generation.

### output
total 40
drwx------@  7 username  staff   224 Nov  5 15:45 .
drwxr-x---+ 42 username  staff  1344 Nov  5 19:18 ..
-rw-r--r--@  1 username  staff   185 Sep 11 19:00 config
-rw-------@  1 username  staff   464 Sep 11 18:24 id_ed25519
-rw-r--r--@  1 username  staff   104 Sep 11 18:24 id_ed25519.pub
-rw-------@  1 username  staff  1842 Oct 25 16:47 known_hosts
-rw-------@  1 username  staff  1106 Oct 25 16:43 known_hosts.old

If we see id_ed25519 and id_ed25519.pub then we already have SSH keys. If we don't want to overwrite them, we will need to specify a different path for the next key generation. If we want to use our existing SSH keys, we can skip the creation step and continue to Connecting to a remote repository.

Create a New SSH Key

# input
ssh-keygen -t ed25519 -C "your_email@example.com"

-t is the algorithm type, -C (optional) is custom comment.

# output
Generating public/private ed25519 key pair.
Enter file in which to save the key (/Users/username/.ssh/id_ed25519):

Press enter to accept the default path or provide a custom path with the file name.

# output
Enter passphrase (empty for no passphrase):

Passphrase is optional, but I highly recommend entering one to protect the use of our private SSH key.
We will be using ssh-agent later so that we don't have to enter the passphrase every time we make a connection.

# output
# dummy data
Your identification has been saved in /Users/username/.ssh/id_ed25519
Your public key has been saved in /Users/username/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:nds92nn/dsNDsadbjndkansdjsknadkj your_email@example.com
The key's randomart image is:
+--[ED25519 256]--+
|             o.**|
|              o**|
|             ++**|
|          .   +=*|
|        S. . +o*o|
|         o..=.o.=|
|          --o+o+o|
|         ..  o=*=|
|             o+E=|
+----[SHA256]-----+

Locate the Newly Generated SSH Key

Verify whether the key was generated successfully by running:

For public key:

# input
cat ~/.ssh/id_ed25519.pub

Adjust the path if using a custom one.

# output
# dummy data
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIB8Dkha0+XZ9sjd34fGFkeGZkHZck9TZx7Hnm0Dd9e2j bry@yourhost

For private key:

# input
cat ~/.ssh/id_ed25519

Adjust the path if using a custom one.

# output
# dummy data
-----BEGIN OPENSSH PRIVATE KEY-----
b3BlbnNzaC1rZXktZDI1NTE5AAAAIB8Dkha0+XZ9sjd34fGFkeGZkHZck9TZx7Hnm
0Dd9e2j+AAAAAAAAAAAAAAAAAAEAAAAIB8Dkha0+XZ9sjd34fGFkeGZkHZck9TZx7
Hnm0Dd9e2j+AAAAAlkdiJHDU6FOSZDa7yxptjMNxzHxgtid7YKm2GFjdjXaAAAAAE
2jxKVmksl3Dbjoef1H5/tf1sgYnJe+JqfgvUhrBgkgmfhdAAAAAAEAAAXLS1mhdhd
bHJdkfHZ9GFFX3NNMgVdk+KfbkhTgyg==
-----END OPENSSH PRIVATE KEY-----

If everything is done correctly, we should see our public and private key in the output as shown above.

Connect to a Remote Repository

Add Public Key to Remote Repository

We need to add our public key to the remote repository platform we are using. Visit one of these links:

GitHub: https://github.com/settings/keys
GitLab: https://gitlab.com/-/profile/keys
Bitbucket: https://bitbucket.org/account/settings/ssh-keys/

Note: Links provided may become invalid in the future as I don't have control over any changes the platforms might make.

Click New SSH Key or Add SSH Key.

Give the key a descriptive name.

Copy the public key from the local machine:

# input
pbcopy < ~/.ssh/id_ed25519.pub

Adjust the path if using a custom one.

Paste the public key in the Key field and save.

Add Our Private SSH Key to the `ssh-agent`

First, we need to start the ssh-agent running in the background.

Mac:

exec ssh-agent zsh

WSL using bash:

exec ssh-agent bash

Windows (I haven't tested this):

CMD:

start-ssh-agent

PowerShell:

Start-Service ssh-agent

Then add the private key to the agent:

ssh-add C:\path\to\your\key

Set Up the SSH Config File

Check if we have an existing ssh config file.

cat ~/.ssh/config

If we don't have one, create a new config file.

touch ~/.ssh/config
open ~/.ssh/config

Update our config file based on the remote host we are using.

For example:

# For GitHub
Host github.com
  AddKeysToAgent yes
  UseKeychain yes # macOS only
  IdentityFile ~/.ssh/id_ed25519

UseKeychain will save our passphrase in the keychain, which will be used to unlock our private key when we make a connection.
This way, we don’t have to enter the passphrase again every time we start a new session or restart our computer.

Test the SSH Connection

# input
# github
ssh -T git@github.com
# gitlab
ssh -T git@gitlab.com
# bitbucket
ssh -T git@bitbucket.org

If everything goes well, we should see the following output:

# output
Hi username! You've successfully authenticated, but GitHub does not provide shell access.

Now we are ready to connect, clone repositories, and push changes to our remote repository!

Wrapping Up

To recap what we covered in this post: we started by understanding why SSH is a better choice than HTTPS for connecting to remote repositories. Then we generated an Ed25519 key pair, added the public key to a remote repository platform, configured the SSH agent and SSH config file for convenience, and finally tested the connection. We should now be able to push, pull, and clone repositories over SSH without entering credentials every time.

Questions Worth Exploring

These topics go deeper into some of the concepts we touched on in this post. I will cover them in future posts.

Why is a passphrase necessary? We mentioned that a passphrase protects our private key, but what exactly happens if someone gets access to our private key without a passphrase?
What is ssh-agent and how does it work? We used ssh-agent to avoid entering our passphrase repeatedly, but how does it actually store and manage our keys in memory?

What Are Web Components, and Why Use Them? A React Example

Bryan Primus Lumbantobing — Mon, 13 Sep 2021 15:25:32 +0000

What Are Web Components?

Let's start with the definition of Web Components.

Based on webcomponents.org:

Web components are a set of web platform APIs that allow you to create new custom, reusable, encapsulated HTML tags to use in web pages and web apps. Custom components and widgets built on Web Component standards work across modern browsers and can be used with any JavaScript library or framework that works with HTML.

From this definition, we know that using web components allows us to create reusable components for any project that uses HTML. Web components are essentially a set of custom, self-contained HTML tags, not tied to any specific library or framework.

Why Does This Matter?

Let's say your company runs multiple web applications. One is built in React, one in Vue, and another in plain HTML. Your design team wants a consistent <app-button> that looks and behaves the same everywhere.

With a framework component, you'd have to rebuild it three times, once per stack. With a web component, you build it once and it just works everywhere. That's the core value.

A web component works the same way in a React app, a Vue app, or no framework at all.

This matters especially if you're building a shared UI library, such as a design system, a component kit, or any set of elements meant to be consumed across different teams or projects. Web components let you ship those elements without forcing everyone to adopt the same framework.

Real companies have taken this approach. GitHub started small, creating components like <relative-time> and <local-time>, then gradually scaled up to more complex ones like <markdown-toolbar-element>. Web components gave them modularity and reusability, letting them build portable elements that fit into their existing codebase without committing to any specific framework.

The Three Building Blocks

Web components are built on three browser APIs that work together:

Custom Elements define what your tag does. You create a class, register it under a tag name, and the browser treats it like any built-in HTML element.

Shadow DOM gives your component its own isolated DOM tree. Styles defined inside it won't leak out to the rest of the page, and global styles won't bleed in either. Shadow DOM fixes CSS and DOM scoping problems. Without any extra tools or naming conventions, you can bundle CSS with markup, hide implementation details, and author self-contained components in vanilla JavaScript.

HTML Templates let you define markup with <template> and <slot> that is parsed but not rendered until you explicitly use it, making it efficient to reuse structure across multiple instances.

These three work independently, but combining them is where you get true encapsulation.

Building a Web Component from Scratch

Let's build a minimal <user-greeting> component that accepts a name attribute and renders a styled greeting. This walks through the whole flow end to end.

Step 1: Define the component file (user-greeting.js)

class UserGreeting extends HTMLElement {
  connectedCallback() {
    // 1. Create a shadow root to isolate this component's DOM and styles
    const shadow = this.attachShadow({ mode: 'open' });

    // 2. Read the attribute passed in from HTML
    const name = this.getAttribute('name') || 'stranger';

    // 3. Build the internal structure
    shadow.innerHTML = `
      <style>
        p {
          font-family: sans-serif;
          color: #333;
          background: #f0f4ff;
          padding: 8px 12px;
          border-radius: 6px;
          display: inline-block;
        }
      </style>
      <p>Hello, ${name}!</p>
    `;
  }
}

// 4. Register the tag name
customElements.define('user-greeting', UserGreeting);

Step 2: Use it in HTML

<!DOCTYPE html>
<html>
  <head>
    <script type="module" src="./user-greeting.js"></script>
  </head>
  <body>
    <user-greeting name="Ada"></user-greeting>
    <user-greeting name="Grace"></user-greeting>
  </body>
</html>

That's it. Both elements render independently with the same component. The <style> inside the shadow DOM only affects what's inside it and won't touch anything else on the page.

Note two things here: the tag name must contain a hyphen (like user-greeting) to distinguish custom elements from built-in ones, and you register it once with customElements.define().

Lifecycle Callbacks

Web components expose lifecycle callbacks you can hook into:

connectedCallback: Runs when the element is inserted into the DOM. This is where you typically do your setup.
disconnectedCallback: Runs when the element is removed from the DOM. Good for cleanup.
attributeChangedCallback: Runs when one of the element's observed attributes changes. Requires you to declare which attributes to watch via static get observedAttributes().
adoptedCallback: Runs when the element is moved to a new document.

If you want the component to react when the name attribute changes, here's how you wire that up:

class UserGreeting extends HTMLElement {
  static get observedAttributes() {
    return ['name']; // declare what to watch
  }

  connectedCallback() {
    this.render();
  }

  attributeChangedCallback() {
    this.render(); // re-render when attribute changes
  }

  render() {
    if (!this.shadowRoot) {
      this.attachShadow({ mode: 'open' });
    }
    const name = this.getAttribute('name') || 'stranger';
    this.shadowRoot.innerHTML = `<p>Hello, ${name}!</p>`;
  }
}

customElements.define('user-greeting', UserGreeting);

Using a Web Component Inside React

Because React renders to HTML, you can drop any web component directly into JSX.

function App() {
  return (
    <div>
      <h1>Welcome</h1>
      <user-greeting name="Ada"></user-greeting>
    </div>
  );
}

One thing to note: when using a web component inside JSX, you use class instead of className. This is because web components are native HTML elements, not React elements, and className is a JSX-specific convention for React's own DOM handling.

// React element: use className
<div className="card">...</div>

// Web component (native HTML element): use class
<user-greeting class="card" name="Ada"></user-greeting>

Also worth knowing: prior to React 19, custom events from web components didn't propagate through React's event system automatically, so you had to attach them via addEventListener manually. React 19 adds native support for custom events, allowing developers to add event listeners using the familiar on + CustomEventName convention, just like standard events such as onClick.

Using React Inside a Web Component

You can also go the other direction and render a React component inside a web component. This is useful when migrating an existing React app toward a web component based architecture.

import ReactDOM from 'react-dom/client';

class SearchWidget extends HTMLElement {
  connectedCallback() {
    const mountPoint = document.createElement('span');
    this.attachShadow({ mode: 'open' }).appendChild(mountPoint);

    const query = this.getAttribute('query');
    const url = 'https://www.google.com/search?q=' + encodeURIComponent(query);

    // Render a React component inside the shadow DOM
    const root = ReactDOM.createRoot(mountPoint);
    root.render(<a href={url}>{query}</a>);
  }
}

customElements.define('search-widget', SearchWidget);

Example adapted from the React documentation

This is then usable in plain HTML like any other custom element:

<search-widget query="web components"></search-widget>

A Note on Tooling

Web components work in all major browsers without any framework or build tool. For simple cases, a <script type="module"> pointing to your component file is all you need.

That said, when you're building a larger project or integrating with React, a bundler like Webpack or Vite is recommended, especially if you're writing JSX inside a web component as in the example above.

If you find the raw API verbose, libraries like Lit offer a lightweight layer on top that adds reactive properties and template rendering while keeping you on web standards.

Summary

Web components solve one specific problem really well: write once, use anywhere. They're not a replacement for React or Vue, but they work alongside them. The real advantage shows up when you're building something meant to be shared across different applications or frameworks, such as a design system, a utility widget, or a standalone UI element that needs to outlive any single framework choice.

Next: Try building a small shared component with web components, or explore Lit for a more ergonomic authoring experience.

Forem: Bryan Primus Lumbantobing

Graceful Shutdown in Go

TL;DR

Example Scenario

HTTP Server in Go

Moving to a Background Goroutine

Communicating with Channels

Understanding Context

Listening for Shutdown Signals

Waiting on Multiple Channels with Select

Shutting Down the Server

Cleaning Up Resources

Putting It All Together

Testing It Manually

Wrapping Up

Using SSH to Connect Local Git to Remote Repositories

TL;DR

SSH and Git

Benefits of Using SSH over HTTPS

Security

Convenience

Generate SSH Keys

Check Existing SSH Keys

Create a New SSH Key

Locate the Newly Generated SSH Key

Connect to a Remote Repository

Add Public Key to Remote Repository

Add Our Private SSH Key to the ssh-agent

Set Up the SSH Config File

Test the SSH Connection

Wrapping Up

Questions Worth Exploring

Links

What Are Web Components, and Why Use Them? A React Example

What Are Web Components?

Why Does This Matter?

The Three Building Blocks

Building a Web Component from Scratch

Lifecycle Callbacks

Using a Web Component Inside React

Using React Inside a Web Component

A Note on Tooling

Summary

Further Reading

Add Our Private SSH Key to the `ssh-agent`