DEV Community: Richard

Adventure: Building with NATS Jetstream KV Store -Part 10

Richard — Tue, 18 Feb 2025 04:44:04 +0000

Hello again! We're back!

Welcome back again to my adventure series on the NATS JetStream Key/Value Store!

We're getting close! We just need to make the Dashboard and the Game routes! Let's go!

Where did we leave off now?

We had just finished setting up logging into our application and saving sessions. Get ready, the meat of our application is starting now!

Getting into the thick of it

The Dashboard route has a lot more going on. We're going to be watching for games created by us and any other person playing. We need to keep track of state for these games, such as if the game is available to join or full. We also need to watch for other actions such as game deletions!

This should be fun! Let's start with the code itself and break it down! Let's checkout setupDashboardRoute().

setupDashboardRoute

package routes

import (
    "context"
    "encoding/json"
    "fmt"
    "log"
    "net/http"
    "strings"
    "time"

    "github.com/delaneyj/toolbelt"
    "github.com/go-chi/chi/v5"
    "github.com/goombaio/namegenerator"
    "github.com/gorilla/sessions"
    "github.com/nats-io/nats.go/jetstream"
    "github.com/rphumulock/ds_nats_ttt/web/components"
    "github.com/rphumulock/ds_nats_ttt/web/pages"

    datastar "github.com/starfederation/datastar/sdk/go"
)

func setupDashboardRoute(router chi.Router, store sessions.Store, js jetstream.JetStream) error {
    ctx := context.Background()

    gameLobbiesKV, err := js.KeyValue(ctx, "gameLobbies")
    if err != nil {
        return fmt.Errorf("failed to get game lobbies key value: %w", err)
    }

    gameBoardsKV, err := js.KeyValue(ctx, "gameBoards")
    if err != nil {
        return fmt.Errorf("failed to get game lobbies key value: %w", err)
    }

    usersKV, err := js.KeyValue(ctx, "users")
    if err != nil {
        return fmt.Errorf("failed to get users key value: %w", err)
    }

    handleGetDashboard := func(w http.ResponseWriter, r *http.Request) {
        sessionId, err := getSessionId(store, r)
        if err != nil {
            http.Error(w, err.Error(), http.StatusInternalServerError)
            return
        }
        if sessionId == "" {
            http.Redirect(w, r, "/", http.StatusSeeOther)
            return
        }

        user, _, err := GetObject[components.User](ctx, usersKV, sessionId)
        if err != nil {
            deleteSessionId(store, w, r)
            http.Redirect(w, r, "/", http.StatusSeeOther)
            return
        }

        pages.Dashboard(user.Name).Render(r.Context(), w)
    }

    router.Get("/dashboard", handleGetDashboard)

    // API

    generateGameDetails := func() (string, string) {
        id := toolbelt.NextEncodedID()
        seed := time.Now().UTC().UnixNano()
        nameGenerator := namegenerator.NewNameGenerator(seed)
        name := strings.ToUpper(nameGenerator.Generate())
        return id, name
    }

    createGameLobby := func(id, name, sessionId string) components.GameLobby {
        return components.GameLobby{
            Id:           id,
            Name:         name,
            HostId:       sessionId,
            ChallengerId: "",
        }
    }

    createGameState := func(id string) components.GameState {
        return components.GameState{
            Id:      id,
            Board:   [9]string{},
            XIsNext: true,
            Winner:  "",
        }
    }

    handleCreate := func(w http.ResponseWriter, r *http.Request) {
        sessionId, err := getSessionId(store, r)
        if err != nil {
            http.Error(w, err.Error(), http.StatusInternalServerError)
            return
        }
        id, name := generateGameDetails()
        gameLobby := createGameLobby(id, name, sessionId)
        if err := PutData(r.Context(), gameLobbiesKV, id, gameLobby); err != nil {
            http.Error(w, fmt.Sprintf("failed to store game lobby: %v", err), http.StatusInternalServerError)
            return
        }
        gameState := createGameState(id)
        if err := PutData(r.Context(), gameBoardsKV, id, gameState); err != nil {
            http.Error(w, fmt.Sprintf("failed to store game state: %v", err), http.StatusInternalServerError)
            return
        }
    }

    handleLogout := func(w http.ResponseWriter, r *http.Request) {
        ctx := r.Context()
        sessionId, err := getSessionId(store, r)
        if err != nil {
            http.Error(w, err.Error(), http.StatusInternalServerError)
            return
        }
        if sessionId == "" {
            http.Redirect(w, r, "/", http.StatusSeeOther)
            return
        }

        keys, err := gameLobbiesKV.Keys(ctx)
        if err != nil {
            log.Printf("%v", err)
        }

        for _, key := range keys {
            entry, err := gameLobbiesKV.Get(ctx, key)
            if err != nil {
                log.Printf("Failed to get value for key %s: %v", key, err)
                continue
            }

            var gameLobby components.GameLobby
            if err := json.Unmarshal(entry.Value(), &gameLobby); err != nil {
                log.Printf("Error unmarshalling update value: %v", err)
                return
            }

            if gameLobby.HostId == sessionId {
                gameLobbiesKV.Delete(ctx, key)
                gameBoardsKV.Delete(ctx, key)
            }
        }

        if err := usersKV.Delete(ctx, sessionId); err != nil {
            http.Error(w, fmt.Sprintf("failed to delete key '%s': %v", sessionId, err), http.StatusInternalServerError)
            return
        }
        deleteSessionId(store, w, r)
        sse := datastar.NewSSE(w, r)
        sse.Redirect("/")
    }

    handleHistoricalUpdates := func(dashboardItems []components.GameLobby, sessionId string, sse *datastar.ServerSentEventGenerator) {
        if len(dashboardItems) == 0 {
            return
        }

        c := components.DashboardList(dashboardItems, sessionId)
        if err := sse.MergeFragmentTempl(c); err != nil {
            sse.ConsoleError(err)
        }
        dashboardItems = nil
    }

    handleKeyValueDelete := func(historicalMode bool, update jetstream.KeyValueEntry, sse *datastar.ServerSentEventGenerator) {
        if historicalMode {
            log.Printf("Ignoring historical delete for key: %s", update.Key())
            return
        }

        if err := sse.RemoveFragments("#game-"+update.Key(),
            datastar.WithRemoveSettleDuration(1*time.Millisecond),
            datastar.WithRemoveUseViewTransitions(false)); err != nil {
            sse.ConsoleError(err)
        }

    }

    handleKeyValuePut := func(
        ctx context.Context,
        historicalMode bool,
        dashboardItems *[]components.GameLobby,
        entry jetstream.KeyValueEntry,
        sessionId string,
        sse *datastar.ServerSentEventGenerator,
    ) {
        var gameLobby components.GameLobby
        if err := json.Unmarshal(entry.Value(), &gameLobby); err != nil {
            log.Printf("Error unmarshalling update value for key %s: %v", entry.Key(), err)
            return
        }

        if historicalMode {
            *dashboardItems = append(*dashboardItems, gameLobby)
            return
        }

        history, err := gameLobbiesKV.History(ctx, entry.Key())
        if err != nil {
            log.Printf("Error getting history for key %s: %v", entry.Key(), err)
            return
        }

        c := components.DashboardListItem(&gameLobby, sessionId)
        if len(history) == 1 {
            if err := sse.MergeFragmentTempl(c,
                datastar.WithSelectorID("list-container"),
                datastar.WithMergeAppend()); err != nil {
                sse.ConsoleError(err)
            }
        } else {
            if err := sse.MergeFragmentTempl(c,
                datastar.WithSelectorID("game-"+entry.Key()),
                datastar.WithMergeMorph()); err != nil {
                sse.ConsoleError(err)
            }
        }
    }

    handleUpdates := func(w http.ResponseWriter, r *http.Request) {
        ctx := r.Context()
        sse := datastar.NewSSE(w, r)

        sessionId, err := getSessionId(store, r)
        if err != nil {
            http.Error(w, err.Error(), http.StatusInternalServerError)
            return
        }

        watcher, err := gameLobbiesKV.WatchAll(ctx)
        if err != nil {
            http.Error(w, fmt.Sprintf("Failed to start watcher: %v", err), http.StatusInternalServerError)
            return
        }
        defer watcher.Stop()

        historicalMode := true
        dashboardItems := &[]components.GameLobby{}

        for {
            select {
            case <-ctx.Done():
                log.Println("Context canceled, stopping watcher updates")
                return
            case entry, ok := <-watcher.Updates():
                if !ok {
                    log.Println("Watcher updates channel closed")
                    return
                }

                if entry == nil {
                    handleHistoricalUpdates(*dashboardItems, sessionId, sse)
                    historicalMode = false
                    continue
                }

                switch entry.Operation() {
                case jetstream.KeyValuePut:
                    handleKeyValuePut(ctx, historicalMode, dashboardItems, entry, sessionId, sse)
                case jetstream.KeyValuePurge:
                    handleKeyValueDelete(historicalMode, entry, sse)
                }
            }
        }
    }

    handlePurge := func(w http.ResponseWriter, r *http.Request) {
        ctx := r.Context()

        keys, err := gameLobbiesKV.Keys(ctx)
        if err != nil {
            log.Printf("Error listing keys: %v", err)
            return
        }

        for _, key := range keys {
            err = gameLobbiesKV.Purge(ctx, key)
            if err != nil {
                log.Printf("Error deleting key '%s': %v", key, err)
                continue
            }

            err = gameBoardsKV.Purge(ctx, key)
            if err != nil {
                log.Printf("Error deleting key '%s': %v", key, err)
                continue
            }

            log.Printf("Deleted key: %s", key)
        }

        fmt.Fprintln(w, "All games have been purged.")
    }

    handleJoin := func(w http.ResponseWriter, r *http.Request) {
        ctx := r.Context()
        sse := datastar.NewSSE(w, r)

        id := chi.URLParam(r, "id")
        if id == "" {
            http.Error(w, "missing 'id' parameter", http.StatusBadRequest)
            return
        }

        sessionID, err := getSessionId(store, r)
        if err != nil {
            http.Error(w, fmt.Sprintf("failed to get session: %v", err), http.StatusInternalServerError)
            return
        }
        if sessionID == "" {
            http.Redirect(w, r, "/", http.StatusSeeOther)
            return
        }

        gameLobby, entry, err := GetObject[components.GameLobby](ctx, gameLobbiesKV, id)
        if err != nil {
            http.Redirect(w, r, "/", http.StatusSeeOther)
            return
        }

        if sessionID != gameLobby.HostId {

            if gameLobby.ChallengerId != "" && gameLobby.ChallengerId != sessionID {
                sse.Redirect("/dashboard")
                sse.ExecuteScript("alert('Another player has already joined. Game is full.');")
                return
            }

            gameLobby.ChallengerId = sessionID

            if err := UpdateData(ctx, gameLobbiesKV, id, gameLobby, entry); err != nil {
                sse.ExecuteScript("alert('Someone else joined first. This lobby is now full.');")
                sse.Redirect("/dashboard")
                return
            }
        }

        sse.Redirect("/game/" + id)
    }

    handleDelete := func(w http.ResponseWriter, r *http.Request) {
        ctx := r.Context()

        id := chi.URLParam(r, "id")
        if id == "" {
            http.Error(w, "missing 'id' parameter", http.StatusBadRequest)
            return
        }

        if err := gameLobbiesKV.Purge(ctx, id); err != nil {
            http.Error(w, fmt.Sprintf("failed to delete key '%s': %v", id, err), http.StatusInternalServerError)
            return
        }
        if err := gameBoardsKV.Purge(ctx, id); err != nil {
            http.Error(w, fmt.Sprintf("failed to delete key '%s': %v", id, err), http.StatusInternalServerError)
            return
        }
    }

    router.Route("/api/dashboard", func(dashboardRouter chi.Router) {

        dashboardRouter.Post("/create", handleCreate)

        dashboardRouter.Post("/logout", handleLogout)

        dashboardRouter.Get("/updates", handleUpdates)

        dashboardRouter.Delete("/purge", handlePurge)

        dashboardRouter.Route("/{id}", func(gameIdRouter chi.Router) {

            gameIdRouter.Post("/join", handleJoin)

            gameIdRouter.Delete("/delete", handleDelete)

        })

    })

    return nil
}

Break it down!

Let's break this bad mamma-jamma down. When we first hit the route we render the page after checking the session and getting the user so we can pass the users name to our component template. We use GetObject() as a helper function to do this. Go ahead and add this function to routes/utils.go.


func GetObject[T any](ctx context.Context, kv jetstream.KeyValue, key string) (*T, jetstream.KeyValueEntry, error) {
    entry, err := kv.Get(ctx, key)
    if err != nil {
        return nil, nil, fmt.Errorf("failed to get key %s: %w", key, err)
    }

    var obj T
    if err := json.Unmarshal(entry.Value(), &obj); err != nil {
        return nil, nil, fmt.Errorf("failed to unmarshal value for key %s: %w", key, err)
    }

    return &obj, entry, nil
}

We will be using this function more in the future.

    handleGetDashboard := func(w http.ResponseWriter, r *http.Request) {
        sessionId, err := getSessionId(store, r)
        if err != nil {
            http.Error(w, err.Error(), http.StatusInternalServerError)
            return
        }
        if sessionId == "" {
            http.Redirect(w, r, "/", http.StatusSeeOther)
            return
        }

        user, _, err := GetObject[components.User](ctx, usersKV, sessionId)
        if err != nil {
            deleteSessionId(store, w, r)
            http.Redirect(w, r, "/", http.StatusSeeOther)
            return
        }

        pages.Dashboard(user.Name).Render(r.Context(), w)
    }

    router.Get("/dashboard", handleGetDashboard)

Let's create that template now.

$ touch components/dashboard.templ

Copy this into it.

package components

import (
    "fmt"
    datastar "github.com/starfederation/datastar/sdk/go"
)

templ Dashboard(name string) {
    {{
        isAdmin := name == "admin"
    }}
    <div data-on-load={ datastar.GetSSE("/api/dashboard/updates") }>
        <div class="flex flex-col sm:flex-row items-center p-4 bg-accent shadow-md w-full mb-4 rounded-md">
            <div class="flex flex-col sm:flex-row gap-3 w-full sm:w-auto">
                <button
                    class="btn btn-primary rounded-md flex items-center justify-center text-center text-primary-content px-4 py-2 sm:px-6 sm:py-3 w-full sm:w-auto"
                    data-on-click={ datastar.PostSSE("/api/dashboard/create") }
                >
                    🎮 Create Game
                </button>
                <button
                    class="btn btn-secondary rounded-md px-4 py-2 sm:px-6 sm:py-3 text-secondary-content w-full sm:w-auto"
                    data-on-click={ datastar.PostSSE("/api/dashboard/logout") }
                >
                    🚪 Logout
                </button>
                if (isAdmin) {
                    <button
                        class="btn btn-error rounded-md flex items-center justify-center text-center text-error-content px-4 py-2 sm:px-6 sm:py-3 w-full sm:w-auto"
                        data-on-click={ datastar.DeleteSSE("/api/dashboard/purge") }
                    >
                        🗑️ Delete Games
                    </button>
                }
            </div>
        </div>
        <div
            id="list-container"
            class="grid grid-cols-1 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4 w-full overflow-y-auto"
            style="max-height: 75vh;"
        ></div>
    </div>
}

templ DashboardList(list []GameLobby, sessionId string) {
    <div
        id="list-container"
        class="grid grid-cols-1 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4 w-full overflow-y-auto"
        style="max-height: 75vh;"
    >
        for _, listItem := range list {
            @DashboardListItem(&listItem, sessionId)
        }
    </div>
}

templ DashboardListItem(gameLobby *GameLobby, sessionId string) {
    {{
        isHost := gameLobby.HostId == sessionId
        isChallenger := gameLobby.ChallengerId == sessionId
        isFull := gameLobby.ChallengerId != ""

        gameSelector := fmt.Sprintf("game-%s", gameLobby.Id)
        showJoinButton := isHost || isChallenger || !isFull

        var status string
        if isFull && !isHost && !isChallenger {
            status = "🔒 Game is Full"
        } else if isFull && isHost {
            status = "✅ Game is Ready!"
        } else if isFull && isChallenger {
            status = "✅ Game is Ready!"
        } else {
            status = "🟢 Game is Open"
        }

        colorClass := "bg-base-300 text-base-content"
        if isHost {
            colorClass = "bg-base-100 text-primary-content"
        }

        cardClasses := fmt.Sprintf("p-6 shadow-lg flex flex-col w-full min-h-[220px] rounded-md %s", colorClass)
    }}
    <div id={ gameSelector } class={ cardClasses }>
        <p class="tracking-widest text-secondary-content text-sm font-bold">
            🎮 Game: { gameLobby.Name }
        </p>
        <p class="tracking-widest text-secondary-content text-sm font-bold">
            📊 Status: { status }
        </p>
        <div class="flex flex-col items-center justify-center w-full gap-2">
            if showJoinButton {
                <button
                    class="btn btn-primary rounded-md flex items-center justify-center text-center text-primary-content w-full m-2 h-12 px-4"
                    data-on-click={ datastar.PostSSE("/api/dashboard/%s/join", gameLobby.Id) }
                >
                    🕹️ Join
                </button>
            }
            if isHost {
                <button
                    class="btn btn-secondary rounded-md flex items-center justify-center text-center text-secondary-content w-full m-2 h-12 px-4"
                    data-on-click={ datastar.DeleteSSE("/api/dashboard/%s/delete", gameLobby.Id) }
                >
                    🗑️ Delete
                </button>
            }
        </div>
    </div>
}

Here we have three components. One for the Dashboard page itself, one for the list of items on the Dashboard and one for the items themselves.

So you see when we land on the Dashboard route, we show the Dashboard page which will call our updates endpoint on load.

<div data-on-load={ datastar.GetSSE("/api/dashboard/updates")

What does this end up doing?

dashboardRouter.Get("/updates", handleUpdates)

Let's check it out!

    handleUpdates := func(w http.ResponseWriter, r *http.Request) {
        ctx := r.Context()
        sse := datastar.NewSSE(w, r)

        sessionId, err := getSessionId(store, r)
        if err != nil {
            http.Error(w, err.Error(), http.StatusInternalServerError)
            return
        }

        watcher, err := gameLobbiesKV.WatchAll(ctx)
        if err != nil {
            http.Error(w, fmt.Sprintf("Failed to start watcher: %v", err), http.StatusInternalServerError)
            return
        }
        defer watcher.Stop()

        historicalMode := true
        dashboardItems := &[]components.GameLobby{}

        for {
            select {
            case <-ctx.Done():
                log.Println("Context canceled, stopping watcher updates")
                return
            case entry, ok := <-watcher.Updates():
                if !ok {
                    log.Println("Watcher updates channel closed")
                    return
                }

                if entry == nil {
                    handleHistoricalUpdates(*dashboardItems, sessionId, sse)
                    historicalMode = false
                    continue
                }

                switch entry.Operation() {
                case jetstream.KeyValuePut:
                    handleKeyValuePut(ctx, historicalMode, dashboardItems, entry, sessionId, sse)
                case jetstream.KeyValuePurge:
                    handleKeyValueDelete(historicalMode, entry, sse)
                }
            }
        }
    }

Does anything look familiar? It should! This is entirely powered by NATS Jetstream KV Store watch command!

All we do is get the id of the current game from the url parameters. We then simply watch on that key! We've done this before!

If you recall, it will always iterate over the historical data before streaming new current events. We use the variable historicalMode to keep track of this.

 historicalMode := true
        dashboardItems := &[]components.GameLobby{}

        for {
            select {
            case <-ctx.Done():
                log.Println("Context canceled, stopping watcher updates")
                return
            case entry, ok := <-watcher.Updates():
                if !ok {
                    log.Println("Watcher updates channel closed")
                    return
                }

                if entry == nil {
                    handleHistoricalUpdates(*dashboardItems, sessionId, sse)
                    historicalMode = false
                    continue
                }

                switch entry.Operation() {
                case jetstream.KeyValuePut:
                    handleKeyValuePut(ctx, historicalMode, dashboardItems, entry, sessionId, sse)
                case jetstream.KeyValuePurge:
                    handleKeyValueDelete(historicalMode, entry, sse)
                }
            }
        }

As events come in from the stream, historical or current, we check the operation type. Let's check out when it is a put operation.

handleKeyValuePut

First, let's talk about historical events.

handleKeyValuePut := func(
        ctx context.Context,
        historicalMode bool,
        dashboardItems *[]components.GameLobby,
        entry jetstream.KeyValueEntry,
        sessionId string,
        sse *datastar.ServerSentEventGenerator,
    ) {
        var gameLobby components.GameLobby
        if err := json.Unmarshal(entry.Value(), &gameLobby); err != nil {
            log.Printf("Error unmarshalling update value for key %s: %v", entry.Key(), err)
            return
        }

        if historicalMode {
            *dashboardItems = append(*dashboardItems, gameLobby)
            return
        }

If the event was historical and being replayed and was a put operation, we simply get the event and unmarshal it into our struct and then add it to a slice. Then we can see, back in our loop over our stream, once all historical events are played we call handleHisotricalUpdates()

handleHistoricalUpdates := func(dashboardItems []components.GameLobby, sessionId string, sse *datastar.ServerSentEventGenerator) {
        if len(dashboardItems) == 0 {
            return
        }

        c := components.DashboardList(dashboardItems, sessionId)
        if err := sse.MergeFragmentTempl(c); err != nil {
            sse.ConsoleError(err)
        }
        dashboardItems = nil
    }

This function simply takes that array and creates a list of the items. Then using Datastar, we merge that lits into the UI. Easy peasy.

What about real time updates?

Glad you asked Let's check out the code again.

   case entry, ok := <-watcher.Updates():
                if !ok {
                    log.Println("Watcher updates channel closed")
                    return
                }

                if entry == nil {
                    handleHistoricalUpdates(*dashboardItems, sessionId, sse)
                    historicalMode = false
                    continue
                }

                switch entry.Operation() {
                case jetstream.KeyValuePut:
                    handleKeyValuePut(ctx, historicalMode, dashboardItems, entry, sessionId, sse)
                case jetstream.KeyValuePurge:
                    handleKeyValueDelete(historicalMode, entry, sse)
                }
            }

Once historical events are finished, we set the historicalMode variable to false. Now when we get new put events we do something else in handleKeyValuePut()

 if historicalMode {
            *dashboardItems = append(*dashboardItems, gameLobby)
            return
        }

        history, err := gameLobbiesKV.History(ctx, entry.Key())
        if err != nil {
            log.Printf("Error getting history for key %s: %v", entry.Key(), err)
            return
        }

        c := components.DashboardListItem(&gameLobby, sessionId)
        if len(history) == 1 {
            if err := sse.MergeFragmentTempl(c,
                datastar.WithSelectorID("list-container"),
                datastar.WithMergeAppend()); err != nil {
                sse.ConsoleError(err)
            }
        } else {
            if err := sse.MergeFragmentTempl(c,
                datastar.WithSelectorID("game-"+entry.Key()),
                datastar.WithMergeMorph()); err != nil {
                sse.ConsoleError(err)
            }
        }

If we are not receiving historical updates anymore, we continue on and create a DashboardListItem component. Check it out-we use the History command here!

We use the history command to check the history of the key. If it's freshly created, we want to append it to the DOM, so using Datastar we do just that and append it to the list. If it's not just being created then it already exists in the DOM and we're performing a different operation on the list item itself, so we morph it. This will take place to alter the list items information for everyone to see!

This is all that this is doing. We iterate over the historical events from our stream-when they are finished the event entry will be nil. This is how we know that the historical replay of events is over with. We then just set the historicalMode variable to reflect this.

After that, any event that occurs is a current/in the moment event. So we can see that for historical events we call handleHistoricalUpdates() and for current events we check the operation type and call either handleKeyValuePut() or handleKeyValueDelete().

Delete is rather simple.

 if historicalMode {
            log.Printf("Ignoring historical delete for key: %s", update.Key())
            return
        }

        if err := sse.RemoveFragments("#game-"+update.Key(),
            datastar.WithRemoveSettleDuration(1*time.Millisecond),
            datastar.WithRemoveUseViewTransitions(false)); err != nil {
            sse.ConsoleError(err)
        }

If it's a historical delete, we simply ignore it. The item was deleted and we don't need to react to this at all. If it's live, then we remove the specific DashboardListItem based on it's key!

This is it for live updates, it's really that easy. This code isn't even that good and it works well. I really should refactor it to make it better!

NATS Jetstream makes it so easy to do this sort of thing on the fly.

What else?

Let's check out some of our other endpoints.

  router.Route("/api/dashboard", func(dashboardRouter chi.Router) {

        dashboardRouter.Post("/create", handleCreate)

        dashboardRouter.Post("/logout", handleLogout)

        dashboardRouter.Get("/updates", handleUpdates)

        dashboardRouter.Delete("/purge", handlePurge)

        dashboardRouter.Route("/{id}", func(gameIdRouter chi.Router) {

            gameIdRouter.Post("/join", handleJoin)

            gameIdRouter.Delete("/delete", handleDelete)

        })

    })

We've covered update. The others are self explanatory but let's go over them anyhow.

Create

Create is fairly straight-forward. Nothing you haven't seen before.

    generateGameDetails := func() (string, string) {
        id := toolbelt.NextEncodedID()
        seed := time.Now().UTC().UnixNano()
        nameGenerator := namegenerator.NewNameGenerator(seed)
        name := strings.ToUpper(nameGenerator.Generate())
        return id, name
    }

    createGameLobby := func(id, name, sessionId string) components.GameLobby {
        return components.GameLobby{
            Id:           id,
            Name:         name,
            HostId:       sessionId,
            ChallengerId: "",
        }
    }

    createGameState := func(id string) components.GameState {
        return components.GameState{
            Id:      id,
            Board:   [9]string{},
            XIsNext: true,
            Winner:  "",
        }
    }

    handleCreate := func(w http.ResponseWriter, r *http.Request) {
        sessionId, err := getSessionId(store, r)
        if err != nil {
            http.Error(w, err.Error(), http.StatusInternalServerError)
            return
        }
        id, name := generateGameDetails()
        gameLobby := createGameLobby(id, name, sessionId)
        if err := PutData(r.Context(), gameLobbiesKV, id, gameLobby); err != nil {
            http.Error(w, fmt.Sprintf("failed to store game lobby: %v", err), http.StatusInternalServerError)
            return
        }
        gameState := createGameState(id)
        if err := PutData(r.Context(), gameBoardsKV, id, gameState); err != nil {
            http.Error(w, fmt.Sprintf("failed to store game state: %v", err), http.StatusInternalServerError)
            return
        }
    }

We generate a name an random id for our game with generateGameDetails(). Then we just use that to create a GameLobby which will be shown on our Dashboard as a DashboardListItem. We also create a new game, instantiating these both with some default values. You can see that a GameLobby is created with the HostId supplied and an empty ChallengerId. You can see the GameState itself defaults to X being first and has no current winner, just an empty board represented by a slice of 9 which represents our game cells.

Logout

Logout is also simple.

 handleLogout := func(w http.ResponseWriter, r *http.Request) {
        ctx := r.Context()
        sessionId, err := getSessionId(store, r)
        if err != nil {
            http.Error(w, err.Error(), http.StatusInternalServerError)
            return
        }
        if sessionId == "" {
            http.Redirect(w, r, "/", http.StatusSeeOther)
            return
        }

        keys, err := gameLobbiesKV.Keys(ctx)
        if err != nil {
            log.Printf("%v", err)
        }

        for _, key := range keys {
            entry, err := gameLobbiesKV.Get(ctx, key)
            if err != nil {
                log.Printf("Failed to get value for key %s: %v", key, err)
                continue
            }

            var gameLobby components.GameLobby
            if err := json.Unmarshal(entry.Value(), &gameLobby); err != nil {
                log.Printf("Error unmarshalling update value: %v", err)
                return
            }

            if gameLobby.HostId == sessionId {
                gameLobbiesKV.Delete(ctx, key)
                gameBoardsKV.Delete(ctx, key)
            }
        }

        if err := usersKV.Delete(ctx, sessionId); err != nil {
            http.Error(w, fmt.Sprintf("failed to delete key '%s': %v", sessionId, err), http.StatusInternalServerError)
            return
        }
        deleteSessionId(store, w, r)
        sse := datastar.NewSSE(w, r)
        sse.Redirect("/")
    }

It's essentially just clean up. We get our session for our current user and then iterate over all of that users Games and delete them all. Then we delete the User. This isn't normal logout behavior but we're doing it just for the sake of this project. In the future maybe I'll make a system that keeps track of users better, but currently this is what we're doing.

Purge

We'll cover the purge endpoint because it's similar. With this, we don't delete the user session, but we do delete all the games that exist. I added this for debugging but also just for a fun learning experience. To use this endpoint, login as admin.

handlePurge := func(w http.ResponseWriter, r *http.Request) {
        ctx := r.Context()

        keys, err := gameLobbiesKV.Keys(ctx)
        if err != nil {
            log.Printf("Error listing keys: %v", err)
            return
        }

        for _, key := range keys {
            err = gameLobbiesKV.Purge(ctx, key)
            if err != nil {
                log.Printf("Error deleting key '%s': %v", key, err)
                continue
            }

            err = gameBoardsKV.Purge(ctx, key)
            if err != nil {
                log.Printf("Error deleting key '%s': %v", key, err)
                continue
            }

            log.Printf("Deleted key: %s", key)
        }

        fmt.Fprintln(w, "All games have been purged.")
    }

Quite simple if you ask me.

Joining and Removing Games

The last two! How do we Join and Remove games? For one of these, we will use the update command! See? We're using all of our commands!

Joining Games

We will be using our update command, let's add a helper for it. In our routes/utils.go file add this.

func UpdateData(ctx context.Context, kv jetstream.KeyValue, id string, data interface{}, entry jetstream.KeyValueEntry) error {
    bytes, err := json.Marshal(data)
    if err != nil {
        return fmt.Errorf("failed to marshal JSON: %w", err)
    }

    _, err = kv.Update(ctx, id, bytes, entry.Revision())
    if err != nil {
        return fmt.Errorf("failed to update key-value: %w", err)
    }

    return nil
}

This will use the current entrys revision number, just like we used earlier in our series, to update our value!

handleJoin := func(w http.ResponseWriter, r *http.Request) {
        ctx := r.Context()
        sse := datastar.NewSSE(w, r)

        id := chi.URLParam(r, "id")
        if id == "" {
            http.Error(w, "missing 'id' parameter", http.StatusBadRequest)
            return
        }

        sessionID, err := getSessionId(store, r)
        if err != nil {
            http.Error(w, fmt.Sprintf("failed to get session: %v", err), http.StatusInternalServerError)
            return
        }
        if sessionID == "" {
            http.Redirect(w, r, "/", http.StatusSeeOther)
            return
        }

        gameLobby, entry, err := GetObject[components.GameLobby](ctx, gameLobbiesKV, id)
        if err != nil {
            http.Redirect(w, r, "/", http.StatusSeeOther)
            return
        }

        if sessionID != gameLobby.HostId {

            if gameLobby.ChallengerId != "" && gameLobby.ChallengerId != sessionID {
                sse.Redirect("/dashboard")
                sse.ExecuteScript("alert('Another player has already joined. Game is full.');")
                return
            }

            gameLobby.ChallengerId = sessionID

            if err := UpdateData(ctx, gameLobbiesKV, id, gameLobby, entry); err != nil {
                sse.ExecuteScript("alert('Someone else joined first. This lobby is now full.');")
                sse.Redirect("/dashboard")
                return
            }
        }

        sse.Redirect("/game/" + id)
    }

Similar stuff, we get the session and the GameLobby and then we check if the person joining is the host or not. If it's the host, we just redirect them to their game. If it's a challenger, we check to make sure the game doesn't already have a challenger. If it does we yell at the person. If it doesn't we add this person as the new challenger.

We haven't saved this to the KV Store yet though, so it's not solid! We attempt to make an update to the store, and if the revision number we had gotten earlier with the GameLobby isn't correct, we yell at this person! (A lot of yelling going on, sheesh!)

We do this because two people might click this at the same time! In the words of Connor and Duncan, THERE CAN BE ONLY ONE!

If all goes well, the challenger is now added and we redirect to the game!

Deleting a Game

This is far more simple.

  handleDelete := func(w http.ResponseWriter, r *http.Request) {
        ctx := r.Context()

        id := chi.URLParam(r, "id")
        if id == "" {
            http.Error(w, "missing 'id' parameter", http.StatusBadRequest)
            return
        }

        if err := gameLobbiesKV.Purge(ctx, id); err != nil {
            http.Error(w, fmt.Sprintf("failed to delete key '%s': %v", id, err), http.StatusInternalServerError)
            return
        }
        if err := gameBoardsKV.Purge(ctx, id); err != nil {
            http.Error(w, fmt.Sprintf("failed to delete key '%s': %v", id, err), http.StatusInternalServerError)
            return
        }
    }

We just get the id of the game and purge it from the lobbies and games buckets.

Wowo! Ok the dashboard should be in working order. Test it and see!

Time to play, let's move on to Part 11 and finish the Game page!

Adventure: Building with NATS Jetstream KV Store -Part 9

Richard — Tue, 11 Feb 2025 00:56:17 +0000

Anddd we're back!

Welcome back again to my adventure series on the NATS JetStream Key/Value Store!

We're finally going to write some code and use the NATS Jetstream KV Store! At last!

Where did we leave off now?

We had just finished using Datastar to hit an endpoint on our server. Now let's use it in conjunction with NATS!

Yay! We're working with NATS again.

Yes we are, let's put it to work and check out some of it's magic in some actual code.

Our application is pretty much just NATS Jetstream doing it's thing and some UI, so let's set up NATS.

In our Router.go, we'll set up the server. Let's change our SetupRoutes() function.

We're going to add embedded NATS into our application. For this, we're going to user a library that wraps some of the work to set NATS up. It's really simple though, we can take a quick peek into what that code is doing.

It's quite simple to do. Grab this code out and then let's talk about it.

Router.go

func SetupRoutes(ctx context.Context, logger *slog.Logger, router chi.Router) (cleanup func() error, err error) {
    natsPort := 1234

    log.Printf("Starting on Nats server %d", natsPort)
    ns, err := embeddednats.New(ctx, embeddednats.WithNATSServerOptions(&server.Options{
        JetStream: true,
        Port:      natsPort,
    }))

    if err != nil {
        return nil, fmt.Errorf("error creating embedded nats server: %w", err)
    }

    ns.WaitForServer()

    cleanup = func() error {
        return errors.Join(
            ns.Close(),
        )
    }

    sessionStore := sessions.NewCookieStore([]byte("session-secret"))
    sessionStore.MaxAge(int(24 * time.Hour / time.Second))

    nc, err := ns.Client()
    if err != nil {
        err = fmt.Errorf("error creating nats client: %w", err)
        return nil, err
    }

    js, err := jetstream.New(nc)
    if err != nil {
        err = fmt.Errorf("error creating nats client: %w", err)
        return nil, err
    }

    createKeyValueBuckets := func(ctx context.Context, js jetstream.JetStream) error {
        createBucket := func(bucket, desc string) error {
            _, err := js.CreateOrUpdateKeyValue(ctx, jetstream.KeyValueConfig{
                Bucket:      bucket,
                Description: desc,
                Compression: true,
                TTL:         time.Hour,
                MaxBytes:    16 * 1024 * 1024,
            })
            if err != nil {
                return fmt.Errorf("error creating bucket %q: %w", bucket, err)
            }
            return nil
        }

        if err := createBucket("gameLobbies", "Datastar Tic Tac Toe Game"); err != nil {
            return err
        }
        if err := createBucket("gameBoards", "Datastar Tic Tac Toe Game"); err != nil {
            return err
        }
        if err := createBucket("users", "Datastar Tic Tac Toe Game"); err != nil {
            return err
        }
        return nil
    }

    if err := createKeyValueBuckets(ctx, js); err != nil {
        return cleanup, err
    }

    if err := errors.Join(
        setupIndexRoute(router, sessionStore, js),
        setupDashboardRoute(router),
        setupGameRoute(router),
    ); err != nil {
        return cleanup, fmt.Errorf("error setting up routes: %w", err)
    }

    return cleanup, nil
}

This package just defines an embedded NATS server that you can launch directly within your Go application. The New function accepts various options for storing data (including where to place JetStream files) and whether to clear existing data before starting.

Internally, it configures and starts a new server.Server from the official NATS library, then watches for a canceled context to gracefully shut everything down. A helper function WaitForServer uses exponential backoff to confirm the NATS server is fully ready for connections, while Client returns a nats.Conn pointing at the server’s client URL so other parts of your application can publish or subscribe.

Not too difficult eh? If you're curious, click into the embeddednats package and check the code out yourself. It's rather simple.

After we set up the server with JetStream support a cleanup function is defined so that shutting down the NATS server is straightforward when you’re finished using it.

Next, the code sets up a session store with a 24-hour cookie lifespan and creates a JetStream client for handling NATS-based streaming features. It then calls a helper to create any necessary Key/Value buckets.

These Buckets are for our Users, Lobbies and Games. We pass the Jetstream instance into our routes so we can leverage it.

So we have NATS set up, nice! Now we need to use it in our routes. Let's start with our Index route.

Index.go

This is where we left off with our Index route.

func setupIndexRoute(router chi.Router) error {

    router.Get("/", func(w http.ResponseWriter, r *http.Request) {
        pages.Index().Render(r.Context(), w)
    })

    router.Route("/api/index", func(indexRouter chi.Router) {

        indexRouter.Get("/", func(w http.ResponseWriter, r *http.Request) {
            sse := datastar.NewSSE(w, r)
            sse.ExecuteScript("alert('Hello from the server!')")

        })

    })

    return nil
}

We need to do some work, we don't want to just send an alert when we hit that endpoint, we want to log in! We also need to keep track of when someone is logged in. How can we do this?

Let's change it to look like this.

package routes

import (
    "context"
    "fmt"
    "net/http"

    "github.com/go-chi/chi/v5"
    "github.com/gorilla/sessions"
    "github.com/nats-io/nats.go/jetstream"
    "github.com/rphumulock/ds_nats_ttt/web/components"
    "github.com/rphumulock/ds_nats_ttt/web/pages"

    datastar "github.com/starfederation/datastar/sdk/go"
)

func setupIndexRoute(router chi.Router, store sessions.Store, js jetstream.JetStream) error {
    ctx := context.Background()

    usersKV, err := js.KeyValue(ctx, "users")
    if err != nil {
        return fmt.Errorf("failed to get 'users' KV bucket: %w", err)
    }

    handleGetIndex := func(w http.ResponseWriter, r *http.Request) {
        sessionID, err := getSessionId(store, r)
        if err != nil {
            http.Error(w, err.Error(), http.StatusInternalServerError)
            return
        }

        if sessionID != "" {
            http.Redirect(w, r, "/dashboard", http.StatusSeeOther)
            return
        }
        pages.Index().Render(r.Context(), w)
    }

    router.Get("/", handleGetIndex)

    // API

    userValidation := func(u *components.InlineValidationUserName) bool {
        return len(u.Name) >= 2
    }

    loadInlineUser := func(r *http.Request) (*components.InlineValidationUserName, error) {
        inlineUser := &components.InlineValidationUserName{}
        if err := datastar.ReadSignals(r, inlineUser); err != nil {
            return nil, err
        }
        return inlineUser, nil
    }

    handleGetLoginComponent := func(w http.ResponseWriter, r *http.Request) {
        inlineUser, err := loadInlineUser(r)
        if err != nil {
            http.Error(w, err.Error(), http.StatusBadRequest)
            return
        }

        sse := datastar.NewSSE(w, r)
        isNameValid := userValidation(inlineUser)
        sse.MergeFragmentTempl(
            components.InlineValidationUserNameComponent(inlineUser, isNameValid),
        )
    }

    createUser := func(sessionId, name string) *components.User {
        return &components.User{
            SessionId: sessionId,
            Name:      name,
        }
    }

    userSession := func(w http.ResponseWriter, r *http.Request, inlineUser *components.InlineValidationUserName) (*components.User, error) {
        ctx := r.Context()

        SessionId, err := createSessionId(store, r, w)
        if err != nil {
            return nil, fmt.Errorf("failed to get session id: %w", err)
        }

        user := createUser(SessionId, inlineUser.Name)

        if err := PutData(ctx, usersKV, user.SessionId, user); err != nil {
            return nil, fmt.Errorf("failed to put user data: %w", err)
        }

        return user, nil
    }

    handlePostLogin := func(w http.ResponseWriter, r *http.Request) {
        inlineUser, err := loadInlineUser(r)
        if err != nil {
            http.Error(w, err.Error(), http.StatusBadRequest)
            return
        }

        if _, err := userSession(w, r, inlineUser); err != nil {
            http.Error(w, err.Error(), http.StatusInternalServerError)
            return
        }

        sse := datastar.NewSSE(w, r)
        sse.Redirect("/dashboard")
    }

    router.Route("/api/index", func(indexRouter chi.Router) {
        indexRouter.Get("/", handleGetLoginComponent)
        indexRouter.Post("/login", handlePostLogin)
    })

    return nil
}

What the Heck?

So what's going on here? We now do some things immediately when we hit our Index page rather than just displaying the page.

 handleGetIndex := func(w http.ResponseWriter, r *http.Request) {
        sessionID, err := getSessionId(store, r)
        if err != nil {
            http.Error(w, err.Error(), http.StatusInternalServerError)
            return
        }

        if sessionID != "" {
            http.Redirect(w, r, "/dashboard", http.StatusSeeOther)
            return
        }
        pages.Index().Render(r.Context(), w)
    }

    router.Get("/", handleGetIndex)

First, we get the sessionId for this user; if the session exists (session isn't an empty string)-it means the user has already logged it. We shoot them off to the dashboard!

Otherwise, we show the Index page. Ok cool, we need to add this getSessionId function. Let's add it to a utilities file because we will need it later!

For this we will use a cookie store with Gorilla sessions. This library just makes it easier to use cookies to keep track of user sessions.

Let's work on this.

$ touch routes/utils.go

Then copy this...

package routes

import (
    "fmt"
    "net/http"

    "github.com/gorilla/sessions"
)

func getSessionId(store sessions.Store, r *http.Request) (string, error) {
    sess, err := store.Get(r, "connections")
    if err != nil {
        return "", fmt.Errorf("failed to get session: %w", err)
    }
    id, ok := sess.Values["id"].(string)
    if !ok || id == "" {
        return "", nil
    }
    return id, nil
}

So now we need to be able to create a session. There isn't a ton of use of getting something if it never exists. We're going to be using Datastar again to create a Login component. First, let's add some handlers. We will need a handler to get the login component and a handler that the login component will use to log in.

Aiming towards Loggin' in...

Let's get the Login component first. We want to be able to grab it immediately upon landing on the Index page. There's many ways to skin a cat (sorry cat lovers, I am also a friend of cats but... it's just a figure of speech!) and we're going to do it in a way that shows off Datastar.

Now remember, when we render our Index page, we have a Datastar data-attribute that will hit our /api/index endpoint on load. Let's add this endpoint and the necessities to show our Login component.

We will need to create a struct to hold input when a user types their name. Let's create a utility file to hold these component structs.

$ touch web/components/utils.go

Then add this...

utils.go

package components

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

And this is how we're showing our Login Component...

    userValidation := func(u *components.InlineValidationUserName) bool {
        return len(u.Name) >= 2
    }

    loadInlineUser := func(r *http.Request) (*components.InlineValidationUserName, error) {
        inlineUser := &components.InlineValidationUserName{}
        if err := datastar.ReadSignals(r, inlineUser); err != nil {
            return nil, err
        }
        return inlineUser, nil
    }

    handleGetLoginComponent := func(w http.ResponseWriter, r *http.Request) {
        inlineUser, err := loadInlineUser(r)
        if err != nil {
            http.Error(w, err.Error(), http.StatusBadRequest)
            return
        }

        sse := datastar.NewSSE(w, r)
        isNameValid := userValidation(inlineUser)
        sse.MergeFragmentTempl(
            components.InlineValidationUserNameComponent(inlineUser, isNameValid),
        )
    }

Let's break this down. First we hit the Index page. We immediately hit our GET /api/index endpoint. This will call our handleGetLoginComponent function. In that function, we call loadInlineUser.

On requests from Datastar, we will send whatever signals are created in it's store. Since we haven't created any it will just continue on with an empty string. So our InlineUserValidation struct will just have an empty name.

Back in handleGetLoginComponent, we wrap the resonse to be a Datastar SSE response and then we validate on the User struct by calling userValidation. As you can see, our name is empty, so it will fail the validation. We then pass this into a component we will create so that Datastar can send it back to the front!

Because we put an id="login" on our div, Datastar will default to targeting the div that called the endpoint. You can also specify another element if you wished by supplying it's selector. How convenient!

Login Component

Let's make the Login component now. Since this is on our Index page, let's make the component for Index.templ. If we needed other components, we could add them to this file as well.

$ touch web/components/Index.templ

Then add this...

package components 

import (
    "fmt"
    datastar "github.com/starfederation/datastar/sdk/go"
)

templ inlineValidationFieldComponent(label, field string, isValid bool, isNotValidErrorLabelFmt string, labelArgs ...any) {
    <div class="form-control">
        <label class="label">
            <span class="label-text">{ label }</span>
        </label>
        <input
            class={ "input input-bordered text-accent rounded-none", templ.KV("input-error", !isValid) }
            data-bind={ field }
            data-on-keydown__debounce.500ms={ datastar.GetSSE("/api/index") }
        />
        if !isValid {
            <label class="text-sm font-bold text-error">{ fmt.Sprintf( isNotValidErrorLabelFmt, labelArgs...) }</label>
        }
    </div>
}

templ InlineValidationUserNameComponent(u *InlineValidationUserName, isNameValid bool) {
    <div id="login" data-signals__ifmissing={ templ.JSONString(u) }>
        <h1 class="text-4xl font-bold text-accent tracking-wide text-center">
            Ready to Play?
        </h1>
        <div class="flex flex-col gap-4">
            @inlineValidationFieldComponent("Enter Your Name:", "name", isNameValid, "Name must be at least 2 characters.")
            <button
                disabled?={ !isNameValid }
                class="btn btn-secondary w-full"
                data-on-click={ datastar.PostSSE("api/index/login") }
            >
                Login
            </button>
        </div>
    </div>
}

InlineValidationUserComponent is our main wrapper. It takes the InlineValidationUser struct that we read in and creates a signal for it.

<div id="login" data-signals__ifmissing={ templ.JSONString(u) }>

This is so Datastar has something to work with. Check out how this works here.

If the name is valid, you will be able to click the button to hit our login endpoint (we haven't made that yet!). The button uses a data-on-click data-attribute and will do a POST to our endpoint. Datastar signals will be sent to the endpoint with our request.

inlineValidationFieldComponent is a helper component that constructs the actual form portion.

<input
class={ "input input-bordered text-accent rounded-none", templ.KV("input-error", !isValid) } 
data-bind={ field }
/>

data-on-keydown__debounce.500ms={ datastar.GetSSE("/api/index") } 
if !isValid {    
    <label class="text-sm font-bold text-error">{ fmt.Sprintf(isNotValidErrorLabelFmt, labelArgs...) }</label>       
}

The data-bind attribute links the input value to our Datastar signal, which we've designated as "Name." This establishes a binding between the provided Name field and the Datastar signals. Additionally, we attach an event listener that triggers when a user types into the input field—debounced to prevent excessive updates with every keystroke. Validation is handled through a boolean parameter passed to the component, ensuring that if the input is invalid, the UI reflects it accordingly.

In the end Datastar will send down our component as an HTML fragment that gets merged into the DOM.

sse.MergeFragmentTempl(components.InlineValidationUserComponent(inlineUser, isNameValid),

Go ahead and check the page out now localhost:8080. You should see a new Login component!

Now all we have to do is write our actual login endpoint that is hit when we click our Login button.

Finally logging in...

We're so close!! This is a part that involves NATS. We're going to go over a little bit more of our setupIndexRoute() function.

    handlePostLogin := func(w http.ResponseWriter, r *http.Request) {
        inlineUser, err := loadInlineUser(r)
        if err != nil {
            http.Error(w, err.Error(), http.StatusBadRequest)
            return
        }

        if _, err := userSession(w, r, inlineUser); err != nil {
            http.Error(w, err.Error(), http.StatusInternalServerError)
            return
        }

        sse := datastar.NewSSE(w, r)
        sse.Redirect("/dashboard")
    }

    router.Route("/api/index", func(indexRouter chi.Router) {
        indexRouter.Get("/", handleGetLoginComponent)
        indexRouter.Post("/login", handlePostLogin)
    })

Let's go over it. When we hit our /login endpoint, we call handlePostLogin(). This function will read in the input for the user name similar to what we were doing before (it's calling the same loadInlineUser() function. Then it will call our userSession() function.

 userSession := func(w http.ResponseWriter, r *http.Request, inlineUser *components.InlineValidationUserName) (*components.User, error) {
        ctx := r.Context()

        SessionId, err := createSessionId(store, r, w)
        if err != nil {
            return nil, fmt.Errorf("failed to get session id: %w", err)
        }

        user := createUser(SessionId, inlineUser.Name)

        if err := PutData(ctx, usersKV, user.SessionId, user); err != nil {
            return nil, fmt.Errorf("failed to put user data: %w", err)
        }

        return user, nil
    }

Here is where we will actually create a user session. We need to add another function to do this. In our routes/utils.go file, add this...

func createSessionId(store sessions.Store, r *http.Request, w http.ResponseWriter) (string, error) {
    session, err := store.Get(r, "connections")
    if err != nil {
        return "", fmt.Errorf("failed to get session: %w", err)
    }
    id := toolbelt.NextEncodedID()
    session.Values["id"] = id
    session.Options.MaxAge = 45 * 60
    if err := session.Save(r, w); err != nil {
        return "", fmt.Errorf("failed to save session: %w", err)
    }
    return id, nil
}

Using Gorilla sessions, we will create a new session that is essentially just a random id for the user. The session lasts 45 minutes. Then we instantiate a User struct with this. Let's add that in now. Add this to our web/components.utils.go file.

web/components.utils.go

type User struct {
    Name      string `json:"name"`
    SessionId string `json:"session_id"`
}

Then we create the actual User.

createUser := func(sessionId, name string) *components.User {
    return &components.User{
        SessionId: sessionId,
        Name:      name,
    }
}

Once we create the User, we pass it to PutData(), which is a helper function to use put with our KV stores.

if err := PutData(ctx, usersKV, user.SessionId, user); err != nil {
    return nil, fmt.Errorf("failed to put user data: %w", err)
}

This time the Users store. Let's make this function since we will use it later. We should place it in our routes/utils.go file. We're using the Jetstream KV Store!! Woo!

routes.utils

func PutData(ctx context.Context, kv jetstream.KeyValue, id string, data interface{}) error {
    bytes, err := json.Marshal(data)
    if err != nil {
        return fmt.Errorf("failed to marshal JSON: %w", err)
    }

    _, err = kv.Put(ctx, id, bytes)
    if err != nil {
        return fmt.Errorf("failed to put key-value: %w", err)
    }

    return nil
}

We're just marshaling the User struct and saving it to the store! Heck yeah. When that's all done Datastar finishes up by sending us off to the Dashboard, because we're logged in!

sse := datastar.NewSSE(w, r)
sse.Redirect("/dashboard")

Nice! Go ahead and check it out!

That was a bit of work but in the end isn't much code when you look at it. It also does validation! We won't need to have front-end and back-end validation that needs to sync like traditional SPA applications (which can be a pain on occasion if you've dealt with it).

Onto the Dashboard in Part 10!

Adventure: Building with NATS Jetstream KV Store -Part 8

Richard — Sat, 08 Feb 2025 04:45:56 +0000

Welcome welcome!

Welcome back again to my adventure series on the NATS JetStream Key/Value Store!

Welcome to Part 8 of our series on the NATS JetStream KV Store! We're finally hitting some real development. We're going to cover how Datastar works a bit and use it to hit our endpoints and display some UI!

Where did we leave off?

We had just created multiple boring pages and styled them in our application. Now let's add more!

Routes routes routes

First, let's create our other routes. We will have 3 pages, an Index page at the root, a Dashboard page for game lobbies and then a page for unique Games.

Let's create them!

$ touch routes/dashboard.go routes/game.go
$ touch web/pages/dashboard.templ web/pages/game.templ

After generating the necessary files, the next step is to define the routes and corresponding pages.

Routes

Dashboard.go

package routes

import (
    "net/http"

    "github.com/go-chi/chi/v5"
    "github.com/rphumulock/ds_nats_ttt/web/pages"
)

func setupDashboardRoute(router chi.Router) error {

    router.Get("/dashboard", func(w http.ResponseWriter, r *http.Request) {
        pages.Dashboard().Render(r.Context(), w)
    })

    return nil
}

This follows the same routing approach we implemented earlier.

Game.go

package routes

import (
    "net/http"

    "github.com/go-chi/chi/v5"
    "github.com/rphumulock/ds_nats_ttt/web/pages"
)

func setupGameRoute(router chi.Router) error {

    router.Get("/game/{id}", func(w http.ResponseWriter, r *http.Request) {
        pages.Game().Render(r.Context(), w)
    })

    return nil
}

Similar to the previous route, but with the addition of a parameter in the endpoint URL. This will hold our unique game ids.

Router.go

func SetupRoutes(ctx context.Context, logger *slog.Logger, router chi.Router) (cleanup func() error, err error) {

    cleanup = func() error {
        return errors.Join()
    }

    if err := errors.Join(
        setupIndexRoute(router),
        setupDashboardRoute(router),
        setupGameRoute(router),
    ); err != nil {
        return cleanup, fmt.Errorf("error setting up routes: %w", err)
    }

    return cleanup, nil
}

Pages

Dashboard.templ

package pages

import "github.com/rphumulock/ds_nats_ttt/web/layouts"

templ Dashboard() {
    @layouts.Base() {
        <div class="flex flex-col min-h-screen max-h-screen overflow-hidden">
            <nav class="bg-base-300 text-base-content py-4 shadow-lg">
                <div class="container mx-auto flex items-center justify-between px-6">
                    <div class="text-2xl font-extrabold tracking-widest uppercase text-secondary-content">
                        Tic Tac Toe
                    </div>
                    <h1 class="text-base sm:text-xl font-semibold text-primary-content text-center flex-1">
                        Welcome, 
                    </h1>
                </div>
            </nav>
            <main class="flex flex-col flex-grow w-full p-4 overflow-hidden">
                <div class="flex flex-col sm:flex-row justify-between items-center p-4 bg-accent shadow-md w-full mb-4">
                    <div class="flex flex-col sm:flex-row gap-3 w-full sm:w-auto">
                        <button
                            class="btn btn-primary rounded-none flex items-center justify-center text-center text-primary-content px-4 py-2 sm:px-6 sm:py-3 w-full sm:w-auto"
                        >
                            Create Game
                        </button>
                        <button
                            class="btn btn-secondary rounded-none px-4 py-2 sm:px-6 sm:py-3 text-secondary-content w-full sm:w-auto"
                        >
                            Logout
                        </button>
                    </div>
                </div>
                <div
                    id="list-container"
                    class="grid grid-cols-1 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4 w-full overflow-y-auto"
                    style="max-height: 75vh;"
                ></div>
            </main>
        </div>
    }
}

Game.templ

package pages

import "github.com/rphumulock/ds_nats_ttt/web/layouts"

templ Game() {
    @layouts.Base() {
        <div class="flex flex-col min-h-screen max-h-screen overflow-hidden">
            <nav class="bg-base-300 text-base-content py-4 shadow-lg">
                <div class="container mx-auto flex items-center justify-between px-6">
                    <div class="text-xl sm:text-2xl font-extrabold tracking-widest uppercase text-secondary-content">
                        Tic Tac Toe
                    </div>
                </div>
            </nav>
            <main id="main-container" class="flex flex-col flex-grow w-full p-4 h-screen">
                <div class="flex flex-col sm:flex-row justify-between items-center p-4 bg-accent shadow-md w-full gap-3">
                    <div class="text-sm sm:text-lg font-bold text-secondary-content text-center">
                        Game:
                    </div>
                    <div class="text-sm sm:text-lg font-bold text-secondary-content text-center">
                        Host:
                    </div>
                    <div class="text-sm sm:text-lg font-bold text-secondary-content text-center">
                        Challenger: 
                    </div>
                    <div class="flex flex-col sm:flex-row gap-3 w-full sm:w-auto"></div>
                </div>
                <div
                    class="flex flex-grow items-center justify-center bg-base-300 mt-2 overflow-y-auto max-h-[75vh] w-full"
                ></div>
            </main>
        </div>
    }
}

Nice! Nothing too wild here—pretty straightforward again-just HTML. Once we run task live, Templ will do the heavy lifting and generate our templates for us. Easy peasy!

Check it out

We can also see our new pages.

Alright, great. We've got buttons that don’t do anything and pages we have to navigate to manually... yeah, this is not it. Let's fix it.

Don't worry, Enter Datastar

Datastar

Ok so what's Datastar about? On the front of the Datastar site it says...

"Datastar helps you build reactive web applications with the simplicity of server-side rendering and the power of a full-stack SPA framework."

Oh neat, another front-end framework. Haha, well sort of but not really. Datastar was born from the same ideas that created HTMX. I'm sure you've heard of it. The approach is a bit different than the common SPA's people use such as React.

A Brief Overview

Traditionally, SPAs rely on JavaScript frameworks like React to fetch JSON from an API and dynamically build the UI. While techniques like Server-Side Rendering (SSR) and WebSockets exist, most applications use a standard request-response cycle, where JSON is retrieved and then rendered into the UI.

HTMX

HTMX, on the other hand, changes this paradigm. Instead of fetching JSON and constructing the UI in JavaScript, it directly requests HTML fragments from the server. These fragments are then dynamically inserted into the DOM without a full page reload, providing a smoother, more efficient experience.

This approach resembles traditional multi-page applications (MPAs), but with the advantage of partial page updates rather than full reloads.

Despite this shift, HTMX still operates in a request-response pattern—you're just receiving ready-to-render HTML instead of raw JSON. This allows you to build rich, interactive applications with minimal JavaScript, keeping logic on the server where it belongs.

For a deeper dive into this, check out HyperMedia Systems, an excellent read where one of the authors happens to be the creator of HTMX.

Datastar

Datastar takes this concept a step further. Like HTMX, it delivers HTML fragments that are rendered directly into the DOM, but instead of a pull-based approach, it operates more like a push from the server.

Rather than fetching HTML on demand, Datastar leverages Server-Sent Events (SSE) to stream HTML fragments from the server to the front-end. While you still initiate a request, the response isn’t limited to a single payload—instead, the server can continuously send one-to-many HTML fragments over time.

SSE establishes a however-long-you-want-lived HTTP connection, unlike traditional request-response cycles where the connection closes immediately after the response is received. With SSE, the server decides when to close the connection, allowing for real-time updates without requiring multiple requests from the client.

SSE is quite literally just a different Content-Type Header on the server.

We've got a high-level overview of Datastar—but don’t worry, there will be a dedicated series on that later. Right now, we're here for NATS, dang it!

So, let’s use Datastar to dive back into some NATS goodness! 🚀

Make our UI do stuff!

Let's add some functionality to those buttons using Datastar! First, we need to get Datastar!

Oh snap! That's easy, we can just use a link tag in our header and the CDN. Let's fix our web/layouts/Base.templ and add Datastar.

Base.Templ

package layouts

templ Base() {
    <!DOCTYPE html>
    <html lang="en" data-theme="retro">
        <head>
            <title>Tic+Tac+Toe</title>
            <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=0"/>
            <script type="module" src="https://cdn.jsdelivr.net/gh/starfederation/datastar@v1.0.0-beta.1/bundles/datastar.js"></script>
            <link href="/static/index.css" rel="stylesheet" type="text/css"/>
            <link rel="icon" type="image/svg+xml" href="/vite.svg"/>
        </head>
        <body class="min-h-screen w-full bg-base-content">
            { children... }
        </body>
    </html>
}

Sweet, let's use it! There's quite a few SDK's created for utilizing Datastar with various languages, but we're sticking with Go!

Let's add the SDK.

$ go get github.com/starfederation/datastar@v1.0.0-beta.5
$ go get github.com/starfederation/datastar/sdk/go@v1.0.0-beta.5

And let's import into our page. We're going to use the alias datastar for it.

package pages

import (
    "github.com/rphumulock/ds_nats_ttt/web/layouts"
    datastar "github.com/starfederation/datastar/sdk/go"
)

templ Index() {
    @layouts.Base() {
        <!-- Full-Screen Container -->
        <div class="flex flex-col min-h-screen max-h-screen overflow-hidden">
            <!-- Navigation Bar -->
            <nav class="bg-base-300 text-base-content py-4 shadow-lg">
                <div class="container mx-auto flex items-center justify-between px-6">
                    <!-- Left: Game Title -->
                    <div class="text-2xl font-extrabold tracking-widest uppercase text-secondary-content">
                        Tic Tac Toe
                    </div>
                </div>
            </nav>
            <!-- Main Content -->
            <main class="min-h-screen flex flex-col items-center justify-center flex-grow gap-6">
            </main>
        </div>
    }
}

This SDK will simply give us syntactic sugar. We'll explain as we add our login functionality.

Login

Let's first think about what we need to do. We want to maintain sessions per User so that we can save Games and Games State on a per User basis.

We will need to login somehow to maintain these sessions. So let's do it.

We're going to add this to our template.

<div id="login" data-on-load={ datastar.GetSSE("/api/index") }></div>

Let's talk about it really quick. What this is doing is tapping into data-attributes which is built into the HTML spec. You can read about them there and we can talk about them more in a Datastar specific series.

Our Datastar data-attribute is data-on-load, which as you make suspect, will do something when the element is loaded into the DOM.

Right away, we’ll make a GET request to an endpoint. Our SDK provides some syntactic sugar with datastar.GetSSE("/api/index"), making the process cleaner.

Under the hood, this function call in our Templ template translates to: "@get('/api/index')".

Without the SDK, we’d just use this string directly—nothing too complex, just a slight convenience. Again, not a big deal, but it keeps things tidy. 🚀

Let's use this in our template.

package pages

import (
    "github.com/rphumulock/ds_nats_ttt/web/layouts"
    datastar "github.com/starfederation/datastar/sdk/go"
)

templ Index() {
    @layouts.Base() {
        <!-- Full-Screen Container -->
        <div class="flex flex-col min-h-screen max-h-screen overflow-hidden">
            <!-- Navigation Bar -->
            <nav class="bg-base-300 text-base-content py-4 shadow-lg">
                <div class="container mx-auto flex items-center justify-between px-6">
                    <!-- Left: Game Title -->
                    <div class="text-2xl font-extrabold tracking-widest uppercase text-secondary-content">
                        Tic Tac Toe
                    </div>
                </div>
            </nav>
            <!-- Main Content -->
            <main class="min-h-screen flex flex-col items-center justify-center flex-grow gap-6">
                <div id="login" data-on-load={ datastar.GetSSE("/api/index") }></div>
            </main>
        </div>
    }
}

Now go ahead and check it out, open your dev-tools (chrome is Ctrl + Shift + i. When we navigate to our Index.page you will see a GET request to /api/index.

It's working! We also did this declaratively and without using any Javascript!

Of course the endpoint is still broken so let's work on that.

Let's fix the Index.go route and add our new endpoint.

Index.go

package routes

import (
    "net/http"

    "github.com/go-chi/chi/v5"
    "github.com/rphumulock/ds_nats_ttt/web/pages"
    datastar "github.com/starfederation/datastar/sdk/go"
)

func setupIndexRoute(router chi.Router) error {

    router.Get("/", func(w http.ResponseWriter, r *http.Request) {
        pages.Index().Render(r.Context(), w)
    })

    router.Route("/api/index", func(indexRouter chi.Router) {

        indexRouter.Get("/", func(w http.ResponseWriter, r *http.Request) {
            sse := datastar.NewSSE(w, r)
            sse.ExecuteScript("alert('Hello from the server!')")

        })

    })

    return nil
}

In Chi, router.Route and router.Get serve different purposes when defining endpoints. router.Get is a simple way to define a single GET request for a specific path, whereas router.Route creates a subrouter that allows grouping multiple related endpoints under a common prefix. This makes router.Route useful for organizing API routes, especially when dealing with multiple endpoints that share a common base path.

In the provided code, router.Route("/api/index", func(indexRouter chi.Router) { sets up a subrouter for /api/index. This means that any additional routes defined within this block will be nested under /api/index/*, keeping the routing structure clean and maintainable. If only a single GET request were needed at /api/index, router.Get("/api/index", handlerFunc) could be used instead.

The line sse := datastar.NewSSE(w, r) initializes a Server-Sent Events (SSE) connection using the Datastar SDK. SSE allows for a persistent connection where the server can push updates to the client without requiring repeated requests. The datastar.NewSSE(w, r) function wraps the HTTP request with the necessary SSE headers, ensuring that the connection remains open for streaming data. This setup enables real-time updates to be sent to the client efficiently.

sse.ExecuteScript("alert('Hello from the server!')")

We're again using the SDK to send a Datastar event.

This will do what it looks like it should: show an alert on the front-end when we hit the endpoint.

Since we're only performing one action the connection will close out after the handler function exits. We could've send 1, 2 and many more events if we wanted to all thanks to SSE and Datastar.

Datastar does the heavy lifting for us!

Ok, we have a nice little introduction. Let's keep building our application in Part 9!

Adventure: Building with NATS Jetstream KV Store -Part 7

Richard — Fri, 07 Feb 2025 20:16:42 +0000

Hey there!

Welcome back again to my adventure series on the NATS JetStream Key/Value Store!

Welcome to Part 7 of our series on the NATS JetStream KV Store! We're going to get right into this because right now our project is very very ugly.

Let's make things pretty!

We're going to add Tailwind CSS to our project.

# Install pnpm and run
$  cd $HOME/Projects/ds_nats_ttt

# Install TailwindCSS
$  pnpm init

# Add TailwindCSS and DaisyUI
$  pnpm add -D tailwindcss@3.4.10 postcss@8.4.41 autoprefixer@10.4.20 daisyui@4.12.10

Awesome sauce! Now that TailwindCSS is in place, it's time to fine-tune our setup by tweaking package.json and tailwind.config.js. These changes will ensure our styles are built efficiently and work seamlessly with our project.

Package.json

Here's my version, but feel free to edit and customize it however you like! Whether you prefer a different approach or just want to add your own touch, go for it!

{
  "name": "ds_nats_ttt",
  "version": "1.0.0",
  "description": "",
  "type": "module",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "autoprefixer": "10.4.20",
    "daisyui": "4.12.10",
    "postcss": "8.4.41",
    "tailwindcss": "3.4.10"
  }
}

Tailwind.Config.js

Let's generate our tailwind config.

# Install our dependencies
$  pnpm i

# Generate your tailwind.config.js
$  pnpm exec tailwindcss init -p

We're bringing DaisyUI themes back into the mix - because, we're lazyUI! Instead of manually styling everything, we'll let DaisyUI handle the heavy lifting.

Since I'm a fan of that old-school aesthetic, I'm rolling with the retro theme. Want to explore all the available themes? You can check them out here and pick one that matches your style!

/** @type {import('tailwindcss').Config} */
import daisyui from "daisyui";

export default {
  content: [
    "./web/**/*.html",
    "./web/**/*.templ",
    "./web/**/*.go",
    "./web/static/*.js",
  ],
  theme: {
    extend: {},
  },
  plugins: [daisyui],
  daisyui: {
    themes: [
      "retro",
    ],
  },
};

To ensure we apply this theme, we need to add a data attribute to our template. This is both fitting and a hint of what's to come because Datastar itself operates using data attributes!

We'll explore this in more detail later, but that's the inspiration behind the name - data-*. Clever, right? I knew you'd catch on!

Add data-theme="retro" to our Index.templ file. We also should add a link tag for our styles.

package layouts

templ Base() {
    <!DOCTYPE html>
    <html lang="en" data-theme="retro">
        <head>
            <title>Tic+Tac+Toe</title>
            <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=0"/>
            <link rel="icon" type="image/x-icon" href=""/>
            <link href="/static/index.css" rel="stylesheet" type="text/css"/>
        </head>
        <body class="min-h-screen w-full bg-base-content">
            { children... }
        </body>
    </html>
}

In our web/styles/styles.css file, add this…

@tailwind base;
@tailwind components;
@tailwind utilities;

Now that TailwindCSS is set up, we could manually generate styles by running commands - but who wants to do that? Remember, we're all about lazyUI! Instead, let's automate the process using Taskfile to handle it for us effortlessly.

Automated build, hot-reload, use some tools to share the load!

Ok that made me sound a bit like Samwise Gamgee but it's ok - because he was the real hero in the end.

Let's create a Taskfile so we can make this entire process easier on ourselves. Go head and install taskfile.

Taskfile

Now all we gotta do is create a Taskfile.yml in our project root.

version: "3"

env:
  STATIC_DIR: "web/static"

tasks:
  # -------------------------------
  # Build Tasks (For Production)
  # -------------------------------

  build:templ:
    desc: "Generate Go templates using templ"
    cmds:
      - go run github.com/a-h/templ/cmd/templ@v0.2.793 generate -v

  build:styles:
    desc: "Compile TailwindCSS styles"
    cmds:
      - pnpm exec tailwindcss -c tailwind.config.js -i web/styles/styles.css -o $STATIC_DIR/index.css

  build:
    desc: "Compile the Go project and generate necessary assets"
    cmds:
      - mkdir -p tmp
      - go build -o tmp/main .
    deps:
      - build:styles
      - build:templ
    parallel: true

  # -------------------------------
  # Debugging Tasks
  # -------------------------------

  debug:
    desc: "Run project with Delve debugger"
    cmds:
      - go run github.com/go-delve/delve/cmd/dlv@v1.23.1 exec ./tmp/main
    deps:
      - build

  # -------------------------------
  # Live Reload (For Development)
  # -------------------------------

  live:templ:
    desc: "Watch for templ changes and regenerate templates"
    cmds:
      - go run github.com/a-h/templ/cmd/templ@v0.2.793 generate --watch --proxy="http://localhost:8080" --open-browser=false -v

  live:styles:
    desc: "Watch and recompile TailwindCSS styles"
    cmds:
      - pnpm exec tailwindcss -c tailwind.config.js -i web/styles/styles.css -o $STATIC_DIR/index.css --watch

  live:server:
    desc: "Auto-reload the Go server with Air"
    cmds:
      - mkdir -p tmp
      - |
        go run github.com/air-verse/air@v1.52.3 \
        --build.cmd "go build -o tmp/main ." \
        --build.bin "tmp/main" \
        --build.delay "100" \
        --build.exclude_dir "node_modules,data,public" \
        --build.include_ext "go" \
        --build.stop_on_error "false" \
        --misc.clean_on_exit true

  live:reload:
    desc: "Watch for changes in static files and trigger a reload"
    cmds:
      - |
        go run github.com/air-verse/air@v1.52.3 \
        --build.cmd "go run github.com/a-h/templ/cmd/templ@v0.2.793 generate --notify-proxy" \
        --build.bin "true" \
        --build.delay "100" \
        --build.exclude_dir "" \
        --build.include_dir "$STATIC_DIR" \
        --build.include_ext "css"

  live:
    desc: "Run the full live-reloading development environment"
    deps:
      - live:templ
      - live:styles
      - live:reload
      - live:server

  # -------------------------------
  # Running the Application
  # -------------------------------

  run:
    desc: "Run the compiled Go binary"
    cmds:
      - ./tmp/main
    deps:
      - build

  default:
    desc: "Default task: runs the application"
    deps:
      - run

We can break this file down--essentially tasks "build" on each other. We start by setting the static directory env variable. Then we have a list of tasks.

env:
  STATIC_DIR: "web/static"

tasks:
  # -------------------------------
  # Build Tasks (For Production)
  # -------------------------------

Tasks can be composed of other tasks. As you can see below we have a build:templ task. It will essentially run templ generate . like we did earlier.

build:templ

build:templ:
    desc: "Generate Go templates using templ"
    cmds:
      - go run github.com/a-h/templ/cmd/templ@v0.2.793 generate -v

We also have a command to build our styles. Pretty straight forward; it runs pnpm exec with tailwindcss to compile off our config based on our base styles. Then we output this to our static directory to serve in our templates.

build:styles

build:styles:
    desc: "Compile TailwindCSS styles"
    cmds:
      - pnpm exec tailwindcss -c tailwind.config.js -i web/styles/styles.css -o $STATIC_DIR/index.css

build

Next we have our actual build task itself. You can see this depends on our styles and templ builds. So one can deduce that we build those first …in parallel? YES! In parallel! Then we build our project main.go.

build:
    desc: "Compile the Go project and generate necessary assets"
    cmds:
      - mkdir -p tmp
      - go build -o tmp/main .
    deps:
      - build:styles
      - build:templ
    parallel: true

debug

We use the delve library to efficiently debug our application, making it easier to inspect and troubleshoot code with precision.

# -------------------------------
  # Debugging Tasks
  # -------------------------------

  debug:
    desc: "Run project with Delve debugger"
    cmds:
      - go run github.com/go-delve/delve/cmd/dlv@v1.23.1 exec ./tmp/main
    deps:
      - build

We also harness the power of Air. We're an airbender for all intents and purposes. This allows us seamless live reloading, ensuring our Go server instantly reflects code changes without manual restarts.

live:templ

This works its magic to regenerate templates, keeps a hawk-eye on changes, slyly proxies requests through localhost:8080, politely refuses to pop open your browser, and runs with all the verbose flair of a chatty parrot.

# -------------------------------
  # Live Reload (For Development)
  # -------------------------------

  live:templ:
    desc: "Watch for templ changes and regenerate templates"
    cmds:
      - go run github.com/a-h/templ/cmd/templ@v0.2.793 generate --watch --proxy="http://localhost:8080" --open-browser=false -v

live:styles

PNPM takes the reins to run TailwindCSS, keeps a watchful eye on our styles, dumps the chic compiled styles our static directory, and recompiles whenever it spots a change.

live:styles:
    desc: "Watch and recompile TailwindCSS styles"
    cmds:
      - pnpm exec tailwindcss -c tailwind.config.js -i web/styles/styles.css -o $STATIC_DIR/index.css --watch

live:server

Air swoops in to reload our Go server, ensures /tmp exists (because it's polite), builds our app and tucks the binary into /tmp/main. Then it watches our Go files, ignores node_modules, data, and public like they're drama, waits a cool 100ms before restarting, powers through errors like a champ, and cleans up after itself like the tidy hero it is.

live:server:
    desc: "Auto-reload the Go server with Air"
    cmds:
      - mkdir -p tmp
      - |
        go run github.com/air-verse/air@v1.52.3 \
        --build.cmd "go build -o tmp/main ." \
        --build.bin "tmp/main" \
        --build.delay "100" \
        --build.exclude_dir "node_modules,data,public" \
        --build.include_ext "go" \
        --build.stop_on_error "false" \
        --misc.clean_on_exit true

live:reload

Air keeps its eyes peeled for CSS changes like a fashion critic, fires up Templ generate the moment it spots an update, stalks our static directory for CSS file drama, and waits a stylish 100ms before hitting that reload button - because good things come to those who (briefly) wait.

live:reload:
    desc: "Watch for changes in static files and trigger a reload"
    cmds:
      - |
        go run github.com/air-verse/air@v1.52.3 \
        --build.cmd "go run github.com/a-h/templ/cmd/templ@v0.2.793 generate --notify-proxy" \
        --build.bin "true" \
        --build.delay "100" \
        --build.exclude_dir "" \
        --build.include_dir "$STATIC_DIR" \
        --build.include_ext "css"

live

I think this one is self-explanatory but we do all the crazy stuff we just did above because this one depends on all of them!

live:
    desc: "Run the full live-reloading development environment"
    deps:
      - live:templ
      - live:styles
      - live:reload
      - live:server

Run

You can see this one just builds our project.

  # -------------------------------
  # Running the Application
  # -------------------------------

  run:
    desc: "Run the compiled Go binary"
    cmds:
      - ./tmp/main
    deps:
      - build

  default:
    desc: "Default task: runs the application"
    deps:
      - run

When all is said and done you can run these commands to do the various things stated above. Go ahead and try it now.

# Let's generate our new styles and then run it
$  task build:styles
$  task live

BOOM! Everything should build and be watching and all the great things stated above. You can go to https://localhost:8080 to confirm and aso check out the hot-reloading proxy at https://localhost:7331.

Holy-moly that was a lot! However we now having a working project that's ready to go! Now we actually get to the fun fun fun part. Making things happen. Part 7!

Adventure: Building with NATS Jetstream KV Store -Part 6

Richard — Fri, 07 Feb 2025 19:18:36 +0000

Welcome back!

Welcome to Part 6 of our series on the NATS JetStream KV Store! Now, we're diving into real development - finally bringing the promised Tic-Tac-Toe game to life.

Where did we leave off?

We had just made a tic-tac-toe game with NATS Jetstream KV Store and the bash shell.

This game will allow players to create unlimited game lobbies, waiting for opponents to join and play. Since this is an ongoing project, we may continue adding features even after this post. But for now, we'll start with a functional, foundational version of the game. Let's go!

Project Stack

First things first - we need to scaffold our project. For this build, I'll be using Go. It's a fun, concise language that gets straight to the point, and even better - NATS is built in Go!

One of the coolest things about this setup is that we can embed a NATS server directly into our application. This means there's no need to set up an external server or containerize anything - unless, of course, you choose to.

Since we're using Go, I've chosen Templ as our template language - it's dynamic, easy to use, and a pleasure to work with. For styling, I've opted for Tailwind CSS, which is both lightweight and simple to set up.

Make sure you have templ-cli installed.

go install github.com/a-h/templ/cmd/templ@latest

To keep things streamlined and avoid managing a separate JavaScript project or worrying about state synchronization, we're using a powerful and fun library called Datastar. I have so much to say about Datastar that I'll be launching another series on it, but for now, here's the short version: it's small, powerful, declarative, and incredibly easy to use. Best of all, it lets us skip the JavaScript hassle entirely! (Kidding… but seriously, haha.)

As we code, we'll cover some high-level aspects of how Datastar works, giving you an understanding of its functionality. However, for a deeper dive into this powerful library, the Datastar series and the Datastar site will provide a more in-depth, hands-on exploration. Stay tuned - there's a lot to love about this tool!

So to list what we're using again:

Golang
NATS
Datastar
SQLite

Every stack needs an acronym. We have MERN, MEAN and LAMP etc. So if you thought about it - the answer is yes, there is an acronym for this stack. I believe it's mostly a joke but the stack is no joke! You should take it very seriously!

Jokes aside, let's keep going.

Getting Started

To get started, we need to set up a basic Go project. Here's how:

# Create the project
$  mkdir $HOME/Projects/ds_nats_ttt

# cd into our project
$  cd $HOME/Projects/ds_nats_ttt

# Initialize a Go module
$  go mod init github.com/<YOUR_NAME>/ds_nats_ttt

# Initialize a Git repository
$  git init

This sets up our project structure, initializes Go module management, and creates a Git repository to track our progress.

Let's keep scaffolding our project. There are many ways to structure a Go project, and I'll be using an approach that fits both my workflow and the needs of this project.

A lot of this project is structured from this repository called Northstar - in fact you'll notice it's close to identical. Well that's because I like it and I'm still learning the best way to go about things myself! Always time to learn something!

# Create our folder structure
$  mkdir -p routes web/components web/layouts web/pages web/static web/styles

# Create our files
$  touch main.go
$  touch routes/index.go routes/router.go
$  touch web/layouts/base.templ web/pages/index.templ web/styles/styles.css

So you'll be left with something like this…

ds_nats_ttt/
├── main.go
├── routes
│   ├── index.go
│   └── router.go
└── web
    ├── components
    ├── layouts
    │   └── base.templ
    ├── pages
    │   └── index.templ
    ├── static
    └── styles
        └── styles.css

Let's do something that's temporary since we haven't pushed this code anywhere. Go into your go.mod file and add these lines. This is so we can reference our local files and Go doesn't try to look them up.

Modify this to fit your directory structure.

replace github.com/<your_name>/ds_nats_ttt/routes => /home/.../Projects/ds_nats_ttt/routes

replace github.com/<your_name>/ds_nats_ttt/web/layouts => /home/.../Projects/ds_nats_ttt/web/layouts

replace github.com/<your_name>/ds_nats_ttt/web/pages => /home/.../Projects/ds_nats_ttt/web/pages

This makes it so when we build our project Go will look for these imports in our local project files.

Our Server

Ok we need to make a server - the brain of our application. Here is the code to create our server. Go ahead and copy this to cmd/web/Main.go

package main

import (
 "context"
 "fmt"
 "log/slog"
 "net/http"
 "os"
 "os/signal"
 "syscall"

 "github.com/rphumulock/ds_nats_ttt/routes"

 "github.com/go-chi/chi/v5"
 "github.com/go-chi/chi/v5/middleware"
 "golang.org/x/sync/errgroup"
)

func main() {

 // Logger Setup – Creates a structured JSON logger (slog) for logging events.
 logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))

 // Port Configuration – Checks for a PORT environment variable; 
 // defaults to 8080 if not set.
 getPort := func() string {
  if p, ok := os.LookupEnv("PORT"); ok {
   return p
  }
  return "8080"
 }

 // Signal Handling – Uses signal.NotifyContext to listen for termination 
 // signals (SIGINT, SIGTERM), ensuring the server shuts down cleanly when 
 // interrupted.
 logger.Info(fmt.Sprintf("Starting Server 0.0.0.0:%s", getPort()))
 defer logger.Info("Stopping Server")

 // Start Server – Calls run() to launch the server, passing the 
 // execution context, logger, and port.
 ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
 defer stop()

 // Error Handling – If run() fails, it logs the error and exits the 
 // program with a non-zero status.
 if err := run(ctx, logger, getPort()); err != nil {
  logger.Error("Error running server", slog.Any("err", err))
  os.Exit(1)
 }
}

// This function ensures the server runs in a controlled environment, 
// handles errors properly, and stops all goroutines when needed.
func run(ctx context.Context, logger *slog.Logger, port string) error {

 // Create an Error Group – Uses errgroup.WithContext to manage 
 // multiple goroutines, ensuring errors propagate properly.
 g, ctx := errgroup.WithContext(ctx)

 // Start the Server – Calls startServer() within a new goroutine so it 
 // runs concurrently.
 g.Go(startServer(ctx, logger, port))

 // Wait for Completion – g.Wait() blocks until all goroutines finish 
 // or one returns an error.
 if err := g.Wait(); err != nil {
  return fmt.Errorf("error running server: %w", err)
 }

 return nil
}

// This function ensures the server runs properly with logging, 
// structured routing, and a clean shutdown process.
func startServer(ctx context.Context, logger *slog.Logger, port string) func() error {
 return func() error {
  router := chi.NewMux()

  // Router Setup - Creates a new Chi router and applies middleware 
  // for logging and panic recovery.
  router.Use(
   middleware.Logger,
   middleware.Recoverer,
  )

  // Static File Handling - Configures the server to serve static files 
  // from the ./static directory.
  router.Handle("/static/*", http.StripPrefix("/static/", http.FileServer(http.Dir("./web/static"))))

  // Route Initialization - Calls SetupRoutes() to register application 
  // routes. If route setup fails, it returns an error. A cleanup function 
  // is deferred to release resources when the server shuts down.
  cleanup, err := routes.SetupRoutes(ctx, logger, router)
  defer cleanup()
  if err != nil {
   return fmt.Errorf("error setting up routes: %w", err)
  }

  // Server Configuration - Creates an HTTP server that listens on 
  // 0.0.0.0:<port> and uses the configured router.
  srv := &http.Server{
   Addr:    "0.0.0.0:" + port,
   Handler: router,
  }

  // Graceful Shutdown - Runs a goroutine that waits for a shutdown 
  // signal (ctx.Done()) and shuts down the server when triggered.
  go func() {
   <-ctx.Done()
   srv.Shutdown(context.Background())
  }()

  return srv.ListenAndServe()
 }
}

These three functions basically just work together to start, run, and manage an HTTP server while ensuring proper error handling and graceful shutdown. The comments will explain what everything does.

How do we get around?

We need to define our routes. If you've noticed our server calling routes.SetupRoutes(), you're absolutely right-that's where we'll configure all our application routes. This function also returns a deferred cleanup() function.

Router.go

package routes

import (
 "context"
 "errors"
 "fmt"
 "log/slog"

 "github.com/go-chi/chi/v5"
)

func SetupRoutes(ctx context.Context, logger *slog.Logger, router chi.Router) (cleanup func() error, err error) {

 cleanup = func() error {
  return errors.Join()
 }

 if err := errors.Join(
  setupIndexRoute(router),
 ); err != nil {
  return cleanup, fmt.Errorf("error setting up routes: %w", err)
 }

 return cleanup, nil
}

Ok but you might also notice this calls another function setupIndexRoute(). Yep! Again you're so smart. We will list all of our routes here but for now where only have one.

Index.go

package routes

import (
 "net/http"

 "github.com/go-chi/chi/v5"
 "github.com/rphumulock/ds_nats_ttt/web/pages"
)

func setupIndexRoute(router chi.Router) error {

 router.Get("/", func(w http.ResponseWriter, r *http.Request) {
  pages.Index().Render(r.Context(), w)
 })

 return nil
}

This is pretty obvious. We're going to render an Index page at our root route. This endpoint takes a GET request.

Let's get our templates in place for our Index page.

I wanna see stuff!

Ok ok ok, soon enough! Let's get our templates in order.

General Layout

Copy this snippet to web/layouts/base.templ.

package layouts

templ Base() {
 <!DOCTYPE html>
 <html lang="en">
  <head>
   <title>Tic+Tac+Toe</title>
   <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=0"/>
   <link rel="icon" type="image/x-icon" href=""/>
  </head>
  <body class="min-h-screen w-full bg-base-content">
   { children... }
  </body>
 </html>
}

This snippet serves as a wrapper for all other templates. It allows us to include global styles and imports in one place, ensuring consistency across the application.

This approach prevents repetitive code in individual templates and ensures that shared elements are available even in other partials where direct inclusion may not be possible.

Landing Page

This is the page we will start on when anyone comes to our application. Copy this to web/pages/Index.templ.

package pages

import "github.com/rphumulock/ds_nats_ttt/web/layouts"

templ Index() {
 @layouts.Base() {
  <!-- Full-Screen Container -->
  <div class="flex flex-col min-h-screen max-h-screen overflow-hidden">
   <!-- Navigation Bar -->
   <nav class="bg-base-300 text-base-content py-4 shadow-lg">
    <div class="container mx-auto flex items-center justify-between px-6">
     <!-- Left: Game Title -->
     <div class="text-2xl font-extrabold tracking-widest uppercase text-secondary-content">
      Tic Tac Toe
     </div>
    </div>
   </nav>
   <!-- Main Content -->
   <main class="min-h-screen flex flex-col items-center justify-center flex-grow gap-6"></main>
  </div>
 }
}

This is simply HTML. You can see we wrap it with our Base.templ file.

You said we would see stuff!

I did and we will. Right now. We need to generate our templates with Templ. You can read more about this here but we're just going to get right to it.

Get Templ with Go and then generate our templates.

# Make sure we're in our project root
$  cd $HOME/Projects/ds_nats_ttt

# Get Templ
$  go get github.com/a-h/templ

# Generate
$  templ generate .

You'll see some files now generated like Index.templ.go. That's a good thing.

Finally let's link things together.

# Get all of our dependencies
$  go mod tidy

Go will fetch all the stuff it needs to put things together. Honestly, if during the course of this you ever run into any weird issues, often running this command will fix things up! Let's run this now!

go run .

Voila! Go to http://localhost:8080 to see a really boring page! Don't worry it will get better because we have so much more to do!
See you in Part 6!

Adventure: Building with NATS Jetstream KV Store -Part 5

Richard — Fri, 07 Feb 2025 19:16:25 +0000

Welcome!

Welcome to Part 5 of our series on the NATS JetStream KV Store! This time, we're going to build a little something - nothing too big just yet, but we're making progress. Stay tuned, because we'll get there!

Where did we leave off?

We did a bunch of CLI commands but let's try to put them to some actual use.

We're going to make Tic Tac Toe in the bash shell!

Terminal Tic Tac Toe

Say that five times fast… actually, it's not that hard. I just did it - did you? You did. Admit it, you totally did.

Alright, enough fun - let's move on! Time to get our setup ready.

First things first let's start fresh again.

# Start NATS Jetstream if you haven't already.
$  ./nats-server -js

# Delete all your buckets!
$  nats kv del <bucket>

# Create the bucket named tictactoe
$  nats kv add tictactoe

It's time to design the main game loop for our Tic-Tac-Toe shell game. While you can simply copy the code, I'll also walk you through how it works. We'll implement five key functions:

Main

The main game loop.

Initialize Board

Resets the game board to its initial state.

Display Board

Displays the current state of the board.

Make Move

Handles moves for players X and O.

Check Winner

Determines if there's a winner. (Pretty self-explanatory!)

Let's get started!

Main Loop

Let's go over the main game loop.

# Main game loop
main() {
  # Displays the main menu and handles user input.
  echo "Welcome to Tic-Tac-Toe with NATS JetStream KV!"
  echo "1. Initialize/Reset Board"
  echo "2. Play Game"
  echo "3. Exit"
  echo "-------------------"

  while :; do
    # Infinite loop to keep showing the menu until the user exits.

    echo -n "Choose an option: "
    read choice
    # Reads the user's menu choice.

    case $choice in
      1)
        initialize_board
        ;;
      2)
        while :; do
          echo "Player $current_player's turn."
          echo "Enter your move (e.g., A1) or press 3 to display the board."
          echo -n "Your input: "
          read cell

          # Handle special commands
          if [[ $cell == "3" ]]; then
            # If the user enters "3", display the board.
            display_board
            continue
          fi

          # Make the move if input is not a special command
          if make_move $cell; then
            if check_winner; then
              # Check if there is a winner and respond if there is.
              current_player="X" # Reset the current player
              break              # Exit to the main menu
            fi
          fi
        done
        ;;
      3)
        echo "Goodbye!"
        exit 0
        ;;
      *)
        echo "Invalid option. Try again."
        ;;
    esac
  done
}

This process is fairly straightforward. Here's how it works:

We start with an outer loop that continues until the user makes a choice between options 1–3:

Clear the board for a new game.
Start the game.
Quit the program.

Once the game starts, we enter an inner loop, which serves as the main game loop. Here's what happens:
The loop pauses at the read command, waiting for the user to provide input.

If the input is the special character 3, it displays the board.
Otherwise, the input is passed to make_move. If the input is valid, it checks for a winner.

Depending on the input and the result the loop either restarts to process more moves, or it exits if a winner is detected.

Initialize the Board

Now we get to use some good ol' fashioned NATS Jetstream KV Store!

# KV bucket name
BUCKET="tictactoe"

# Resets the Tic-Tac-Toe board by initializing all cells in the bucket.
initialize_board() {
  echo "Initializing board..."

  for cell in A1 A2 A3 B1 B2 B3 C1 C2 C3; do
    # Sets each cell in the KV store to an empty space (" ").
    nats kv put $BUCKET $cell " " >/dev/null 2>&1

  done
  echo "Board initialized."
  # Displays the newly initialized board.
  display_board
}

Alright, buckle up - this is where the magic happens, and it's simpler than you think!

We're going to loop through every cell of our Tic-Tac-Toe board and use the nats kv put command to stash an empty space for each one. Think of it like setting up a fresh board where every cell is just waiting for someone to make a move.

Each cell gets its own key-value pair in the bucket, like key=A1, Value=" ". Boom, instant empty board!

>/dev/null: This sneaky bit shushes the success messages from the nats kv put command. No bragging allowed here!
2>&1: And this? It's like saying, "Oh, you messed up? Cool, but we're not telling anyone." Any errors get tossed into the void too.

Once the board is all set up, we'll proudly display it like a freshly baked cake.

Display Board

Oh, this one's a piece of cake! 🍰

Here's the deal: we've got a super simple function called display_board() that does exactly what it says-it shows off our Tic-Tac-Toe board in all its glory.

What's happening under the hood? We're just grabbing the values from JetStream using the nats kv get command for each cell (A1, A2, A3, and so on). Then, we're stitching them together in a way that looks like a proper Tic-Tac-Toe board.

Recognize the pattern? Yep, it's just echoing the values back with some fancy lines (--+---+--) to make it look legit. We use the raw flag to retrieve only the value of the Key from the KV Store - since NATS will give you more data (such as the revision number or time of the event etc) because it's awesome like that.

We don't need the extra data however; just the value.

# Function to display the board
display_board() {
  echo "Current Board:"
  echo "$(nats kv get $BUCKET A1 --raw 2>/dev/null) | $(nats kv get $BUCKET A2 --raw 2>/dev/null) | $(nats kv get $BUCKET A3 --raw 2>/dev/null)"
  echo "--+---+--"
  echo "$(nats kv get $BUCKET B1 --raw 2>/dev/null) | $(nats kv get $BUCKET B2 --raw 2>/dev/null) | $(nats kv get $BUCKET B3 --raw 2>/dev/null)"
  echo "--+---+--"
  echo "$(nats kv get $BUCKET C1 --raw 2>/dev/null) | $(nats kv get $BUCKET C2 --raw 2>/dev/null) | $(nats kv get $BUCKET C3 --raw 2>/dev/null)"
}

Easy enough. What's next?

Make Move

Ok now we're getting to the game logic.

current_player="X"

# Function to make a move
make_move() {
  local cell=$1
  # The cell the player wants to make a move on that was entered.

  # Validate the cell
  if ! [[ $cell =~ ^[ABC][123]$ ]]; then
    # Checks if the input matches a valid cell format (e.g., A1, B2, C3).
    echo "Invalid cell! Please enter a valid cell (e.g., A1, B2, C3)."
    return 1
  fi

  # Check if the cell is already occupied
  local value=$(nats kv get $BUCKET $cell --raw 2>/dev/null)
  # Retrieves the current value of the cell.
  if [[ $value == "X" || $value == "O" ]]; then
    # If the cell is already occupied, show an error.
    echo "Cell $cell is already occupied. Choose another cell."
    return 1
  fi

  # Make the move
  nats kv put $BUCKET $cell $current_player
  # Updates the cell in the KV store with the current player's symbol.
  echo "Player $current_player moved to $cell."

  # Switch to the other player
  if [[ $current_player == "X" ]]; then
    # If the current player is X, switch to O.
    current_player="O"
  else
    # Otherwise, switch to X.
    current_player="X"
  fi

  display_board
  # Show the updated board after the move.
}

Alright, this isn't too complex - it's mostly just JetStream functionality. Here's what happens step by step in make_move:

We take the cell argument passed to the function.
We validate it using a regex to ensure it's a valid board cell (A1 to C3).
We check if the cell is already occupied (i.e., it contains X or O).
If valid and unoccupied, we update the cell's key in the bucket with the current player's symbol (X or O).
Finally, we switch to the next player and display the updated board.

Check Winner

The only semi-complicated function…. but not really.

# Function to check for a winner
check_winner() {
  local board=()
  # Creates an array to store the current state of the board.
  for cell in A1 A2 A3 B1 B2 B3 C1 C2 C3; do
    board+=("$(nats kv get $BUCKET $cell --raw 2>/dev/null)")
    # Populates the board array with the values of each cell.
    # board=("X" "O" " " " " "X" "O" "O" " " "X") etc
  done

  # Winning combinations
  local win_patterns=(
    "0 1 2" "3 4 5" "6 7 8" # Rows
    "0 3 6" "1 4 7" "2 5 8" # Columns
    "0 4 8" "2 4 6"         # Diagonals
  )

  # We constructed the board AND it will look like this:
  # board=("X" "O" " " " " "X" "O" "O" " " "X")

  for pattern in "${win_patterns[@]}"; do
    # Iterates through each winning pattern.
    local i1=$(echo $pattern | cut -d' ' -f1)
    local i2=$(echo $pattern | cut -d' ' -f2)
    local i3=$(echo $pattern | cut -d' ' -f3)

    # local i1=$(echo $pattern | cut -d' ' -f1)
    # Just uses a delimeter of " " and grabs from a string.
    # In our case it's a pattern like "0 1 2"

    # local i1=$(echo $pattern | cut -d' ' -f1) echoes the pattern
    # and pipes it to cut which cuts using the delimeter ' '
    # so we get 0, 1, 2 and then -f1 grabs the first field. So 0.
    # Then we put it in local variable i1.

    # Check if the three cells match and are not empty (not " ")
    if [[ ${board[$i1]} == "${board[$i2]}" && ${board[$i2]} == "${board[$i3]}" && ${board[$i1]} != " " ]]; then

      # For "0 1 2" iimagine. Or "0 4 8
      # If all three cells match and are not empty, a player wins.

      echo "🎉 Player ${board[$i1]} wins! 🎉"
      initialize_board
      # Resets the board for the next game.
      echo "Returning to the main menu..."
      return 0
    fi
  done

  # Check for a tie (no cells contain " ")
  if [[ ! " ${board[*]} " =~ " " ]]; then
    # If no cells are empty, the game is a tie.
    display_board
    echo "It's a tie! 🤝"
    initialize_board
    echo "Returning to the main menu..."
    return 0
  fi

  return 1
  # If no winner or tie is found, the game continues.
}

First we reconstruct the board locally - we iterate over the cell list and get the values from the NATS KV Store accordingly.

Then we set up the win conditions. We iterate over those win conditions and then check them against our local board. If there's a winner we show a celebration message and reset the board!

We then check for a tie and then reset the board if there is one.
If none of the above occurs the game continues.

The Full Game

Go ahead and just copy this.

#!/bin/bash
# Indicates that this script should be run using the Bash shell interpreter.

# KV bucket name
BUCKET="tictactoe"
# Defines the name of the NATS Key-Value bucket used for storing the game state.

current_player="X"
# Tracks the current player, starting with "X".

# Resets the Tic-Tac-Toe board by initializing all cells in the bucket.
initialize_board() {
  echo "Initializing board..."

  for cell in A1 A2 A3 B1 B2 B3 C1 C2 C3; do
    nats kv put $BUCKET $cell " " >/dev/null 2>&1
    # Sets each cell in the KV store to an empty space (" ").
    # 1. >/dev/null: Suppresses the normal success message that 
    # the nats kv put command might generate.
    # 2. 2>&1: Ensures that any errors produced (e.g., if the nats command fails) 
    # are also discarded.
  done
  echo "Board initialized."
  display_board
  # Displays the newly initialized board.
}

# Function to display the board
display_board() {
  echo "Current Board:"
  echo "$(nats kv get $BUCKET A1 --raw 2>/dev/null) | $(nats kv get $BUCKET A2 --raw 2>/dev/null) | $(nats kv get $BUCKET A3 --raw 2>/dev/null)"
  echo "--+---+--"
  echo "$(nats kv get $BUCKET B1 --raw 2>/dev/null) | $(nats kv get $BUCKET B2 --raw 2>/dev/null) | $(nats kv get $BUCKET B3 --raw 2>/dev/null)"
  echo "--+---+--"
  echo "$(nats kv get $BUCKET C1 --raw 2>/dev/null) | $(nats kv get $BUCKET C2 --raw 2>/dev/null) | $(nats kv get $BUCKET C3 --raw 2>/dev/null)"
}

# Function to make a move
make_move() {
  local cell=$1
  # The cell the player wants to make a move on that was entered.

  # Validate the cell
  if ! [[ $cell =~ ^[ABC][123]$ ]]; then
    # Checks if the input matches a valid cell format (e.g., A1, B2, C3).
    echo "Invalid cell! Please enter a valid cell (e.g., A1, B2, C3)."
    return 1
  fi

  # Check if the cell is already occupied
  local value=$(nats kv get $BUCKET $cell --raw 2>/dev/null)
  # Retrieves the current value of the cell.
  if [[ $value == "X" || $value == "O" ]]; then
    # If the cell is already occupied, show an error.
    echo "Cell $cell is already occupied. Choose another cell."
    return 1
  fi

  # Make the move
  nats kv put $BUCKET $cell $current_player
  # Updates the cell in the KV store with the current player's symbol.
  echo "Player $current_player moved to $cell."

  # Switch to the other player
  if [[ $current_player == "X" ]]; then
    # If the current player is X, switch to O.
    current_player="O"
  else
    # Otherwise, switch to X.
    current_player="X"
  fi

  display_board
  # Show the updated board after the move.
}

# Function to check for a winner
check_winner() {
  local board=()
  # Creates an array to store the current state of the board.
  for cell in A1 A2 A3 B1 B2 B3 C1 C2 C3; do
    board+=("$(nats kv get $BUCKET $cell --raw 2>/dev/null)")
    # Populates the board array with the values of each cell.
    # board=("X" "O" " " " " "X" "O" "O" " " "X") etc
  done

  # Winning combinations
  local win_patterns=(
    "0 1 2" "3 4 5" "6 7 8" # Rows
    "0 3 6" "1 4 7" "2 5 8" # Columns
    "0 4 8" "2 4 6"         # Diagonals
  )

  # We constructed the board AND it will look like this:
  # board=("X" "O" " " " " "X" "O" "O" " " "X")

  for pattern in "${win_patterns[@]}"; do
    # Iterates through each winning pattern.
    local i1=$(echo $pattern | cut -d' ' -f1)
    local i2=$(echo $pattern | cut -d' ' -f2)
    local i3=$(echo $pattern | cut -d' ' -f3)

    # local i1=$(echo $pattern | cut -d' ' -f1)
    # Just uses a delimeter of " " and grabs from a string.
    # In our case it's a pattern like "0 1 2"

    # local i1=$(echo $pattern | cut -d' ' -f1) echoes the pattern
    # and pipes it to cut which cuts using the delimeter ' '
    # so we get 0, 1, 2 and then -f1 grabs the first field. So 0.
    # Then we put it in local variable i1.

    # Check if the three cells match and are not empty (not " ")
    if [[ ${board[$i1]} == "${board[$i2]}" && ${board[$i2]} == "${board[$i3]}" && ${board[$i1]} != " " ]]; then

      # For "0 1 2" iimagine. Or "0 4 8
      # If all three cells match and are not empty, a player wins.

      echo "🎉 Player ${board[$i1]} wins! 🎉"
      initialize_board
      # Resets the board for the next game.
      echo "Returning to the main menu..."
      return 0
    fi
  done

  # Check for a tie (no cells contain " ")
  if [[ ! " ${board[*]} " =~ " " ]]; then
    # If no cells are empty, the game is a tie.
    display_board
    echo "It's a tie! 🤝"
    initialize_board
    echo "Returning to the main menu..."
    return 0
  fi

  return 1
  # If no winner or tie is found, the game continues.
}

# Main game loop
main() {
  # Displays the main menu and handles user input.
  echo "Welcome to Tic-Tac-Toe with NATS JetStream KV!"
  echo "1. Initialize/Reset Board"
  echo "2. Play Game"
  echo "3. Exit"
  echo "-------------------"

  while :; do
    # Infinite loop to keep showing the menu until the user exits.
    echo -n "Choose an option: "
    read choice
    # Reads the user's menu choice.

    case $choice in
      1)
        initialize_board
        ;;
      2)
        while :; do
          echo "Player $current_player's turn."
          echo "Enter your move (e.g., A1) or press 3 to display the board."
          echo -n "Your input: "
          read cell

          # Handle special commands
          if [[ $cell == "3" ]]; then
            # If the user enters "3", display the board.
            display_board
            continue
          fi

          # Make the move if input is not a special command
          if make_move $cell; then
            if check_winner; then
              # Check if there is a winner and respond if there is.
              current_player="X" # Reset the current player
              break              # Exit to the main menu
            fi
          fi
        done
        ;;
      3)
        echo "Goodbye!"
        exit 0
        ;;
      *)
        echo "Invalid option. Try again."
        ;;
    esac
  done
}

# Run the main function
main
# Starts the Tic-Tac-Toe game.

Create a file and call it whatever you want - I used tictactoe.sh.

Then chmod +x tictactoe.sh to make it executable.

To Play

Before we finally jump into the game, let me show you one more JetStream command I intentionally held back earlier. After all, this is about JetStream, right?

If you haven't started the NATS Server, do it.

./nats-server -js

Open two terminal windows. In the first one, run:

$ nats kv watch tictactoe

Then, in the second window, start the game by running:

./tictactoe.sh

Now take a look - you're actively watching the stream for the tictactoe Bucket! Pretty awesome, right? You can see all the updates happening in real-time!

./tictactoe.sh 

Welcome to Tic-Tac-Toe with NATS JetStream KV!
1. Initialize/Reset Board
2. Play Game
3. Exit
-------------------
Choose an option: 1
Initializing board...
Board initialized.
Current Board:
  |   |  
--+---+--
  |   |  
--+---+--
  |   |  
Choose an option: 2
Player X's turn.
Enter your move (e.g., A1) or press 3 to display the board.
Your input: A1
X
Player X moved to A1.
Current Board:
X |   |  
--+---+--
  |   |  
--+---+--
  |   |  
Player O's turn.
Enter your move (e.g., A1) or press 3 to display the board.
Your input: B2
O
Player O moved to B2.
Current Board:
X |   |  
--+---+--
  | O |  
--+---+--
  |   |  
Player X's turn.
Enter your move (e.g., A1) or press 3 to display the board.
Your input: C1
X
Player X moved to C1.
Current Board:
X |   |  
--+---+--
  | O |  
--+---+--
X |   |  
Player O's turn.
Enter your move (e.g., A1) or press 3 to display the board.
Your input: F3
Invalid cell! Please enter a valid cell (e.g., A1, B2, C3).
Player O's turn.
Enter your move (e.g., A1) or press 3 to display the board.
Your input: A2
O
Player O moved to A2.
Current Board:
X | O |  
--+---+--
  | O |  
--+---+--
X |   |  
Player X's turn.
Enter your move (e.g., A1) or press 3 to display the board.
Your input: B1
X
Player X moved to B1.
Current Board:
X | O |  
--+---+--
X | O |  
--+---+--
X |   |  
🎉 Player X wins! 🎉
Initializing board...
Board initialized.
Current Board:
  |   |  
--+---+--
  |   |  
--+---+--
  |   |  
Returning to the main menu...
Choose an option: 

This is what you will see in the terminal watching the KV Store.
nats kv watch tictactoe
[2025-01-20 01:23:51] PUT tictactoe > A1:  
[2025-01-20 01:23:51] PUT tictactoe > A2:  
[2025-01-20 01:23:51] PUT tictactoe > A3:  
[2025-01-20 01:23:51] PUT tictactoe > B1:  
[2025-01-20 01:23:51] PUT tictactoe > B2:  
[2025-01-20 01:23:51] PUT tictactoe > B3:  
[2025-01-20 01:23:51] PUT tictactoe > C1:  
[2025-01-20 01:23:51] PUT tictactoe > C2:  
[2025-01-20 01:23:51] PUT tictactoe > C3:  
[2025-01-20 01:24:12] PUT tictactoe > A1: X
[2025-01-20 01:24:14] PUT tictactoe > B2: O
[2025-01-20 01:24:19] PUT tictactoe > C1: X
[2025-01-20 01:24:29] PUT tictactoe > A2: O
[2025-01-20 01:24:34] PUT tictactoe > B1: X
[2025-01-20 01:24:34] PUT tictactoe > A1:  
[2025-01-20 01:24:34] PUT tictactoe > A2:  
[2025-01-20 01:24:34] PUT tictactoe > A3:  
[2025-01-20 01:24:34] PUT tictactoe > B1:  
[2025-01-20 01:24:34] PUT tictactoe > B2:  
[2025-01-20 01:24:34] PUT tictactoe > B3:  
[2025-01-20 01:24:34] PUT tictactoe > C1:  
[2025-01-20 01:24:34] PUT tictactoe > C2:  
[2025-01-20 01:24:34] PUT tictactoe > C3:

Another thing you can do is make a few moves and then close the terminals. If you restart the game you will see it will have maintained the state from where you left off.

$ ./tictactoe.sh 

Welcome to Tic-Tac-Toe with NATS JetStream KV!
1. Initialize/Reset Board
2. Play Game
3. Exit
-------------------
Choose an option: 1
Initializing board...
Board initialized.
Current Board:
  |   |  
--+---+--
  |   |  
--+---+--
  |   |  
Choose an option: 2 
Player X's turn.
Enter your move (e.g., A1) or press 3 to display the board.
Your input: A1
X
Player X moved to A1.
Current Board:
X |   |  
--+---+--
  |   |  
--+---+--
  |   |  
Player O's turn.
Enter your move (e.g., A1) or press 3 to display the board.
Your input: B3
O
Player O moved to B3.
Current Board:
X |   |  
--+---+--
  |   | O
--+---+--
  |   |  
Player X's turn.
Enter your move (e.g., A1) or press 3 to display the board.
Your input: C2
X
Player X moved to C2.
Current Board:
X |   |  
--+---+--
  |   | O
--+---+--
  | X |  
Player O's turn.
Enter your move (e.g., A1) or press 3 to display the board.
Your input: ^C

We quit the game close Jetstream and closed the terminals.

Let's restart it all and start the game.

$ ./tictactoe.sh 

Welcome to Tic-Tac-Toe with NATS JetStream KV!
1. Initialize/Reset Board
2. Play Game
3. Exit
-------------------
Choose an option: 2
Player X's turn.
Enter your move (e.g., A1) or press 3 to display the board.
Your input: 3
Current Board:
X |   |  
--+---+--
  |   | O
--+---+--
  | X |  
Player X's turn.
Enter your move (e.g., A1) or press 3 to display the board.
Your input:

See? State is preserved!

So yeah all of that is pretty cool. I want to apologize for not showing you the watch command earlier because it's rad. Don't worry though you'll be using it again differently soon. We're going to do some actual development now in Part 5!
See ya there!

Adventure: Building with NATS Jetstream KV Store -Part 4

Richard — Fri, 07 Feb 2025 19:13:57 +0000

Welcome back!

Here we are again! Going on my adventure series on the NATS JetStream Key/Value Store!

Welcome to Part 4 of our series exploring the NATS JetStream KV Store!

Where did we leave off?

We left off exploring various commands such create, get, update and put; as well as how check a keys history and revert the keys value to an older revision if we like!

Let's find out how to delete!

Deleting a Key

Ok this one can be a little confusing because there's a few things going on here. Let's just try it though.

Let's start from scratch again, so delete all your Buckets.

Let's create a new Bucket with history=3 and use put to add some values... fill it up!

$ nats kv add --history=3 Bucket1

Information for Key-Value Store Bucket Bucket1 created 2025-02-07T13:50:55-05:00

Configuration:

          Bucket Name: Bucket1
         History Kept: 3
        Values Stored: 0
           Compressed: false
   Backing Store Kind: JetStream
          Bucket Size: 0 B
  Maximum Bucket Size: unlimited
   Maximum Value Size: unlimited
          Maximum Age: unlimited
     JetStream Stream: KV_Bucket1
              Storage: File

Cluster Information:

                 Name: 
               Leader: NAHBJSFROLS2WSIXPPDBIUZXWJX6XIAKK36PTRF72ONLECU22XPPNV23

$ nats kv put Bucket1 Key1 Value1
Value1

$ nats kv put Bucket1 Key1 Value2
Value2

$ nats kv put Bucket1 Key1 Value3
Value3

Now let's delete! We do this with the del command.

$ nats kv del Bucket1 Key1
? Delete key Bucket1 > Key1? Yes

Ok what now? Let's try to get the Key.

$ nats kv get Bucket1 Key1
nats: error: nats: key not found

Ok cool. Let's try make sure it's gone.

$ nats kv ls Bucket1
No keys found in bucket

That looks good. Ok what else can we do to confirm? Let's try it all.

$ nats kv ls
╭────────────────────────────────────────────────────────────────────────────╮
│                              Key-Value Buckets                             │
├─────────┬─────────────┬─────────────────────┬───────┬────────┬─────────────┤
│ Bucket  │ Description │ Created             │ Size  │ Values │ Last Update │
├─────────┼─────────────┼─────────────────────┼───────┼────────┼─────────────┤
│ Bucket1 │             │ 2025-02-07 13:50:55 │ 185 B │ 3      │ 1m17s       │
╰─────────┴─────────────┴─────────────────────┴───────┴────────┴─────────────╯

Wait. 3 values??? What's going on?

$ nats kv history Bucket1 Key1
╭──────────────────────────────────────────────────────────────────╮
│                    History for Bucket1 > Key1                    │
├──────┬──────────┬────────┬─────────────────────┬────────┬────────┤
│ Key  │ Revision │ Op     │ Created             │ Length │ Value  │
├──────┼──────────┼────────┼─────────────────────┼────────┼────────┤
│ Key1 │        2 │ PUT    │ 2025-02-07 13:51:09 │ 6      │ Value2 │
│ Key1 │        3 │ PUT    │ 2025-02-07 13:51:10 │ 6      │ Value3 │
│ Key1 │        4 │ DELETE │ 2025-02-07 13:53:52 │ 0      │        │
╰──────┴──────────┴────────┴─────────────────────┴────────┴────────╯

Ahh there it is! A DELETE Op. So we did in fact delete the key.

This makes sense because we couldn't get the keys value. If you see here it also has a Length of 0 and no Value.

Ok so it's still there in the history as we see under Revision 4.

So NATS is keeping track of this even though it's deleted. That's kind of neat and very purposeful. All events are tracked. We have 3 entries because history was set to 3. If it we're default, we would have 1 entry with a DELETE op. You get it. It's a delete marker added to our key.

Well there's still history there. What if I don't want it taking up space?

We can use kv compact.

Compact

Let's again, check our commands.

Subcommands:
  kv add      Adds a new KV Store Bucket
  kv put      Puts a value into a key
  kv get      Gets a value for a key
  kv create   Puts a value into a key only if the key is new or it's last operation was a delete
  kv update   Updates a key with a new value if the previous value matches the given revision
  kv del      Deletes a key or the entire bucket
  kv purge    Deletes a key from the bucket, clearing history before creating a delete marker
  kv history  Shows the full history for a key
  kv revert   Reverts a value to a previous revision using put
  kv info     View the status of a KV store
  kv watch    Watch the bucket or a specific key for updated
  kv ls       List available buckets or the keys in a bucket
  kv compact  Reclaim space used by deleted keys

Ok, so compact reclaims space used by deleted keys. What does this mean?

$ nats kv compact Bucket1
? Purge all historic values and audit trails for deleted keys in bucket Bucket1? Yes

$ nats kv history Bucket1 Key1
╭─────────────────────────────────────────────────────────────────╮
│                    History for Bucket1 > Key1                   │
├──────┬──────────┬────────┬─────────────────────┬────────┬───────┤
│ Key  │ Revision │ Op     │ Created             │ Length │ Value │
├──────┼──────────┼────────┼─────────────────────┼────────┼───────┤
│ Key1 │        4 │ DELETE │ 2025-02-07 13:53:52 │ 0      │       │
╰──────┴──────────┴────────┴─────────────────────┴────────┴───────╯

Check it out! All the history is gone but we can still see that the key was marked with a DELETE op. We can also see that it happened on Revision 4 on our key.

So essentially compact will remove all the previous revisions that aren't needed anymore for every key marked with a DELETE op.

There's another command that can do this for us on a key by key basis. Let's check it out, it's called purge

Purging Keys

Purge can make this easier by deleting and removing the history in one step for a specified key. You can check out the commands above, as we've printed them out enough now!

Let's try it, but first, what would happen now if we modified Key1 again?

$ nats kv put Bucket1 Key1 Value1
Value1

$ nats kv history Bucket1 Key1

╭──────────────────────────────────────────────────────────────────╮
│                    History for Bucket1 > Key1                    │
├──────┬──────────┬────────┬─────────────────────┬────────┬────────┤
│ Key  │ Revision │ Op     │ Created             │ Length │ Value  │
├──────┼──────────┼────────┼─────────────────────┼────────┼────────┤
│ Key1 │        4 │ DELETE │ 2025-02-07 13:53:52 │ 0      │        │
│ Key1 │        5 │ PUT    │ 2025-02-07 14:04:24 │ 6      │ Value1 │
╰──────┴──────────┴────────┴─────────────────────┴────────┴────────╯

Ohh bully! We appended a new revision to our history which is now 2! We kept track that the recent op was a PUT and we have a value again! We can get it and everything! Try it if you want!

So as you can see, you can use del to remove a key while preserving its history.

If needed, you can compact the Bucket to permanently remove all history of deleted keys.

Let's try purge

$ nats kv purge Bucket1 Key1
? Purge key Bucket1 > Key1? Yes

$ nats kv history Bucket1 Key1
╭────────────────────────────────────────────────────────────────╮
│                   History for Bucket1 > Key1                   │
├──────┬──────────┬───────┬─────────────────────┬────────┬───────┤
│ Key  │ Revision │ Op    │ Created             │ Length │ Value │
├──────┼──────────┼───────┼─────────────────────┼────────┼───────┤
│ Key1 │        6 │ PURGE │ 2025-02-07 14:07:37 │ 0      │       │
╰──────┴──────────┴───────┴─────────────────────┴────────┴───────╯

Ahh! It added a PURGE op. This is just to show that it wasn't simply deleted, the history was also deleted, all in one command! How convenient!

Let's go over one more thing.

Bucket Retention Policy

Yes, there is a tiny bit more to learn. Retention Policy is also a thing.

If the bucket reaches its configured storage limit (e.g., --max-bytes 10MB), older revisions, including delete markers, may be removed to free up space.

There is also TTL on Buckets when you create them. Let's mess with that real quick.

Go ahead and delete all the buckets again and just start from scratch.

Let's use the TTL flag.

$ nats kv add --ttl=30s --history=3 Bucket1

Information for Key-Value Store Bucket Bucket1 created 2025-02-07T14:11:41-05:00

Configuration:

          Bucket Name: Bucket1
         History Kept: 3
        Values Stored: 0
           Compressed: false
   Backing Store Kind: JetStream
          Bucket Size: 0 B
  Maximum Bucket Size: unlimited
   Maximum Value Size: unlimited
          Maximum Age: 30.00s
     JetStream Stream: KV_Bucket1
              Storage: File

Cluster Information:

                 Name: 
               Leader: NAHBJSFROLS2WSIXPPDBIUZXWJX6XIAKK36PTRF72ONLECU22XPPNV23

Now create some keys.

$ nats kv put Bucket1 Key1 Value1
Value1
$ nats kv put Bucket1 Key1 Value2
Value2
$ nats kv put Bucket1 Key1 Value3
Value3

$ nats kv history Bucket1 Key1
╭───────────────────────────────────────────────────────────────╮
│                   History for Bucket1 > Key1                  │
├──────┬──────────┬─────┬─────────────────────┬────────┬────────┤
│ Key  │ Revision │ Op  │ Created             │ Length │ Value  │
├──────┼──────────┼─────┼─────────────────────┼────────┼────────┤
│ Key1 │        1 │ PUT │ 2025-02-07 14:12:23 │ 6      │ Value1 │
│ Key1 │        2 │ PUT │ 2025-02-07 14:12:24 │ 6      │ Value2 │
│ Key1 │        3 │ PUT │ 2025-02-07 14:12:25 │ 6      │ Value3 │
╰──────┴──────────┴─────┴─────────────────────┴────────┴────────╯

Let's wait for 30 seconds.

...Now try!

$ nats kv history Bucket1 Key1
nats: error: nats: key not found

Ok wow. So it's just gone huh?

Yeah we set the expiration time on the Key. We can't even check it's history!

Ok wow. That was a doozy. There's a lot there and stuff we haven't covered but remember; this is an intro series!! (go easy on me!)

I highly recommend you play around with it yourself if anything didn't seem clear. It's easy enough and by now you should have the chops for it!

Alright we went over fundamental CLI commands for NATS Jetstream KV Store. I know, I know --you want to make something.

Ok I get it. Let's make something in Part 5!

Adventure: Building with NATS Jetstream KV Store -Part 3

Richard — Fri, 07 Feb 2025 18:45:58 +0000

Welcome back again!

Welcome to my adventure series on the NATS JetStream Key/Value Store! This is Part 3 of our series exploring the NATS JetStream KV Store! Let's just get to it and keep exploring!

Where did we leave off??

We're were just about to start messing around with lockers… I mean keys! I gotta stop doing that!

Creating Keys

Ok - let's add some keys to these Buckets. For this, we're going to have a Pop Quiz! I want you to delete any Buckets that exist.

What's that? We don't like Pop Quizzes? Ok fine. No Pop Quiz. Just run these commands.

$ nats kv ls              # list your buckets
$ nats kv del <bucket>    # delete them

Now starting fresh let's make a new Bucket.

$ nats kv add Bucket1

Information for Key-Value Store Bucket Bucket1 created 2025-02-07T12:37:39-05:00

Configuration:

          Bucket Name: Bucket1
         History Kept: 1
        Values Stored: 0
           Compressed: false
   Backing Store Kind: JetStream
          Bucket Size: 0 B
  Maximum Bucket Size: unlimited
   Maximum Value Size: unlimited
          Maximum Age: unlimited
     JetStream Stream: KV_Bucket1
              Storage: File

Cluster Information:

                 Name: 
               Leader: NAHBJSFROLS2WSIXPPDBIUZXWJX6XIAKK36PTRF72ONLECU22XPPNV23

As we saw earlier from nats kv -h, we can use the create command to create keys.

Let's try it!

$ nats kv create Bucket1 Key1

Empty output from the response? Let's try again!

$ nats kv create Bucket1 Key1
nats: error: nats: wrong last sequence: 1: key exists

Hmm, what's going on? Let's check the create command again.

$ nats kv

 nats kv
error: a subcommand from the list below is required, use --help for full help including flags and arguments

usage: nats kv <command> [<args> ...]

Interacts with a JetStream based Key-Value store

The JetStream Key-Value store uses streams to store key-value pairs for an indefinite period
or a per-bucket configured TTL.

Subcommands:
  kv add      Adds a new KV Store Bucket
  kv put      Puts a value into a key
  kv get      Gets a value for a key
  kv create   Puts a value into a key only if the key is new or it's last operation was a
              delete
  kv update   Updates a key with a new value if the previous value matches the given revision
  kv del      Deletes a key or the entire bucket
  kv purge    Deletes a key from the bucket, clearing history before creating a delete marker
  kv history  Shows the full history for a key
  kv revert   Reverts a value to a previous revision using put
  kv info     View the status of a KV store
  kv watch    Watch the bucket or a specific key for updated
  kv ls       List available buckets or the keys in a bucket
  kv compact  Reclaim space used by deleted keys

Pass --help to see global flags applicable to this command.

Ok so, it will only create a new key if:

The key is new.
The Key's last operation was a delete.

Ok the key isn't new since we had created it before and it also wasn't previously deleted. This makes sense. It was weird though because we had an empty output upon creation.

Let's check the Bucket.

$ nats kv ls Bucket1
Key1

Ok so the key was definitely created! Let's get it's value.

Reading Keys

Let's check the keys value. For this we can use get.

$ nats kv get Bucket1 Key1



Bucket1 > Key1 revision: 1 created @ 19 Jan 25 03:54 UTC

Once again, we can see that the key is indeed present, along with extra details like its revision and the time it was created.

We’ll cover those details soon, but if you just want the value itself, you can use the raw flag.

$ nats kv get --raw Bucket1 Key1

Nothing, and we had gotten an empty response when we created it. I think a picture is starting to emerge.

Let's try something else to be sure. We can check the history of a key like this.

$ nats kv history Bucket1 Key1

╭──────────────────────────────────────────────────────────────╮
│                  History for Bucket1 > Key1                  │
├──────┬──────────┬─────┬─────────────────────┬────────┬───────┤
│ Key  │ Revision │ Op  │ Created             │ Length │ Value │
├──────┼──────────┼─────┼─────────────────────┼────────┼───────┤
│ Key1 │        1 │ PUT │ 2025-01-18 22:54:59 │ 0      │       │
╰──────┴──────────┴─────┴─────────────────────┴────────┴───────╯

Ohh ok! The Value was empty when we created the key, remember?

You can see the length of the value is 0. If you recall we did nats kv create Bucket1 Key1, not nats kv create Bucket1 Key1 Value1.

We never specified a Value!

Let's thank the history command for solving this mystery. We should probably talk about it!

Key History

So far, we’ve been busy creating keys and checking out their history—but let’s be honest, we’ve been winging it without really understanding.

To clear things up, we need to take a little step back. Let’s start with history (no, not that kind of history, the history of keys!).

When you create a Bucket, you get to decide how it handles keys and keeps track of their changes. Up until now, we’ve been rolling with the default setting, which, by the way, is set to 1.

But what does that even mean? Let’s dig in.

Start fresh again with no Buckets. Delete all the buckets! nats kv del <Bucket>

$ nats kv add --history=3 Bucket1

Information for Key-Value Store Bucket Bucket1 created 2025-02-07T13:01:15-05:00

Configuration:

          Bucket Name: Bucket1
         History Kept: 3
        Values Stored: 0
           Compressed: false
   Backing Store Kind: JetStream
          Bucket Size: 0 B
  Maximum Bucket Size: unlimited
   Maximum Value Size: unlimited
          Maximum Age: unlimited
     JetStream Stream: KV_Bucket1
              Storage: File

Cluster Information:

                 Name: 
               Leader: NAHBJSFROLS2WSIXPPDBIUZXWJX6XIAKK36PTRF72ONLECU22XPPNV23

Notice History Kept: 3 rather than History Kept: 1. If you backtrack you'll see it was 1 when we made a Bucket without using the history flag. Go ahead and scroll up and check!

Ok so we have created a Bucket with History Kept: 3. Let's create a key again and check the history.

$ nats kv create Bucket1 Key1 Value1
Value1

$ nats kv history Bucket1 Key1
╭───────────────────────────────────────────────────────────────╮
│                   History for Bucket1 > Key1                  │
├──────┬──────────┬─────┬─────────────────────┬────────┬────────┤
│ Key  │ Revision │ Op  │ Created             │ Length │ Value  │
├──────┼──────────┼─────┼─────────────────────┼────────┼────────┤
│ Key1 │        1 │ PUT │ 2025-02-07 13:03:56 │ 6      │ Value1 │
╰──────┴──────────┴─────┴─────────────────────┴────────┴────────╯

Ok this makes sense. We only have one entry in the history because we only just created a key. How do we update the value? I want to see my history!

We can use update!

Updating a Key

Let's try updating the key.

$ nats kv update Bucket1 Key1 Value2
nats: error: nats: wrong last sequence: 1

Wait what? Maybe we should check what update does?

Subcommands:
  kv add      Adds a new KV Store Bucket
  kv put      Puts a value into a key
  kv get      Gets a value for a key
  kv create   Puts a value into a key only if the key is new or it's last operation was a delete
  kv update   Updates a key with a new value if the previous value matches the given revision
  kv del      Deletes a key or the entire bucket
  kv purge    Deletes a key from the bucket, clearing history before creating a delete marker
  kv history  Shows the full history for a key
  kv revert   Reverts a value to a previous revision using put
  kv info     View the status of a KV store
  kv watch    Watch the bucket or a specific key for updated
  kv ls       List available buckets or the keys in a bucket
  kv compact  Reclaim space used by deleted keys

Ahh ok! It will only update the value if the previous value matches the given revision. We didn't give a revision.

What was the revision again?

$ nats kv history Bucket1 Key1

╭───────────────────────────────────────────────────────────────╮
│                   History for Bucket1 > Key1                  │
├──────┬──────────┬─────┬─────────────────────┬────────┬────────┤
│ Key  │ Revision │ Op  │ Created             │ Length │ Value  │
├──────┼──────────┼─────┼─────────────────────┼────────┼────────┤
│ Key1 │        1 │ PUT │ 2025-02-07 13:03:56 │ 6      │ Value1 │
╰──────┴──────────┴─────┴─────────────────────┴────────┴────────╯

Duh! It was Revision 1. The first revision! Since we had only created the key. Let's supply the revision!

$ nats kv update Bucket1 Key1 Value2 1
Value2

Bingo Bango Bongo! We got it!

For fun let's check the history again!

$ nats kv history Bucket1 Key1

╭───────────────────────────────────────────────────────────────╮
│                   History for Bucket1 > Key1                  │
├──────┬──────────┬─────┬─────────────────────┬────────┬────────┤
│ Key  │ Revision │ Op  │ Created             │ Length │ Value  │
├──────┼──────────┼─────┼─────────────────────┼────────┼────────┤
│ Key1 │        1 │ PUT │ 2025-02-07 13:03:56 │ 6      │ Value1 │
│ Key1 │        2 │ PUT │ 2025-02-07 13:09:54 │ 6      │ Value2 │
╰──────┴──────────┴─────┴─────────────────────┴────────┴────────╯

Oh neat! We have another revision and another entry! This is because we set history=3! If you had created the Bucket with history=1 or omitted the history flag and went with default, you wouldn't see two entries!

Let's experiment. Create another Bucket with history=1. Then we will add a key and then update that key and check the history.

$ nats kv add Bucket2

Information for Key-Value Store Bucket Bucket2 created 2025-02-07T13:14:22-05:00

Configuration:

          Bucket Name: Bucket2
         History Kept: 1
        Values Stored: 0
           Compressed: false
   Backing Store Kind: JetStream
          Bucket Size: 0 B
  Maximum Bucket Size: unlimited
   Maximum Value Size: unlimited
          Maximum Age: unlimited
     JetStream Stream: KV_Bucket2
              Storage: File

Cluster Information:

                 Name: 
               Leader: NAHBJSFROLS2WSIXPPDBIUZXWJX6XIAKK36PTRF72ONLECU22XPPNV23

$ nats kv create Bucket2 Key1 Value1
Value1

$ nats kv update Bucket2 Key1 Value2 1
Value2

$ nats kv history Bucket2 Key1
╭───────────────────────────────────────────────────────────────╮
│                   History for Bucket2 > Key1                  │
├──────┬──────────┬─────┬─────────────────────┬────────┬────────┤
│ Key  │ Revision │ Op  │ Created             │ Length │ Value  │
├──────┼──────────┼─────┼─────────────────────┼────────┼────────┤
│ Key1 │        2 │ PUT │ 2025-02-07 13:14:32 │ 6      │ Value2 │
╰──────┴──────────┴─────┴─────────────────────┴────────┴────────╯

See! There's still only 1 entry, whereas Bucket1 has 2 entries! You can see the revision number is 2 but there's still just 1 entry!

Let's mess with Bucket1 again. Let's update the key twice and see what happens.

nats kv update Bucket1 Key1 Value3 2
Value3

$ nats kv history Bucket1 Key1
╭───────────────────────────────────────────────────────────────╮
│                   History for Bucket1 > Key1                  │
├──────┬──────────┬─────┬─────────────────────┬────────┬────────┤
│ Key  │ Revision │ Op  │ Created             │ Length │ Value  │
├──────┼──────────┼─────┼─────────────────────┼────────┼────────┤
│ Key1 │        1 │ PUT │ 2025-02-07 13:03:56 │ 6      │ Value1 │
│ Key1 │        2 │ PUT │ 2025-02-07 13:09:54 │ 6      │ Value2 │
│ Key1 │        3 │ PUT │ 2025-02-07 13:16:45 │ 6      │ Value3 │
╰──────┴──────────┴─────┴─────────────────────┴────────┴────────╯

$ nats kv update Bucket1 Key1 Value4 3
Value4

$ nats kv history Bucket1 Key1
╭───────────────────────────────────────────────────────────────╮
│                   History for Bucket1 > Key1                  │
├──────┬──────────┬─────┬─────────────────────┬────────┬────────┤
│ Key  │ Revision │ Op  │ Created             │ Length │ Value  │
├──────┼──────────┼─────┼─────────────────────┼────────┼────────┤
│ Key1 │        2 │ PUT │ 2025-02-07 13:09:54 │ 6      │ Value2 │
│ Key1 │        3 │ PUT │ 2025-02-07 13:16:45 │ 6      │ Value3 │
│ Key1 │        4 │ PUT │ 2025-02-07 13:17:05 │ 6      │ Value4 │
╰──────┴──────────┴─────┴─────────────────────┴────────┴────────╯

See! 3 entries! We no longer have Revision 1. It's sort of like a stack but revision 1 was replaced when the revisions went over the configured history number.

Bucket1 has a history of 3 and keeps track of up to 3 revisions.
Bucket2 has a history of 1 and keeps track of up to 1 revision.

Makes sense.

Ok updating each time and having to provide a revision number can be annoying. What if we just want to change the value and not worry about a revision number?

We can use put!

Updating a key with `put`

Like Bernie Sanders, once again I am going to ask you to check our commands.

Subcommands:
  kv add      Adds a new KV Store Bucket
  kv put      Puts a value into a key
  kv get      Gets a value for a key
  kv create   Puts a value into a key only if the key is new or it's last operation was a delete
  kv update   Updates a key with a new value if the previous value matches the given revision
  kv del      Deletes a key or the entire bucket
  kv purge    Deletes a key from the bucket, clearing history before creating a delete marker
  kv history  Shows the full history for a key
  kv revert   Reverts a value to a previous revision using put
  kv info     View the status of a KV store
  kv watch    Watch the bucket or a specific key for updated
  kv ls       List available buckets or the keys in a bucket
  kv compact  Reclaim space used by deleted keys

Ok so put just puts a value into our key, nothing else is necessary. Let's try it.

$ nats kv put Bucket1 Key1 Value5
Value5

$ nats kv history Bucket1 Key1

╭───────────────────────────────────────────────────────────────╮
│                   History for Bucket1 > Key1                  │
├──────┬──────────┬─────┬─────────────────────┬────────┬────────┤
│ Key  │ Revision │ Op  │ Created             │ Length │ Value  │
├──────┼──────────┼─────┼─────────────────────┼────────┼────────┤
│ Key1 │        3 │ PUT │ 2025-02-07 13:16:45 │ 6      │ Value3 │
│ Key1 │        4 │ PUT │ 2025-02-07 13:17:05 │ 6      │ Value4 │
│ Key1 │        5 │ PUT │ 2025-02-07 13:33:51 │ 6      │ Value5 │
╰──────┴──────────┴─────┴─────────────────────┴────────┴────────╯

There we go. We changed the value of Key1 to Value5 now. We also increased the revision number in the history which still has 3 entries.

put makes things easy when you need it to be!

Let's go over the write commands for the keys.

Ok so, what’s the difference between Create, Put and Update?

Create

Ensures a new key is added only if it doesn’t already exist, failing if the key is present. Use when you want to ensure a key is added without risk of overwriting.

Put

Sets a value for a key, creating it if it doesn’t exist or overwriting it if it does. Use for general-purpose operations where overwriting is acceptable.

Update

Updates a key’s value only if its current revision matches a specified version, ensuring safe conditional updates. Use for conditional updates where revision conflicts need to be avoided.

Sweet! Easy-peasy!

There was also another command in there you might have noticed called revert.

Let's check it out.

Revert

What if you want to revert to a previous value. Well-- it's a great thing we have history! NATS is great man!

$ nats kv history Bucket1 Key1

╭───────────────────────────────────────────────────────────────╮
│                   History for Bucket1 > Key1                  │
├──────┬──────────┬─────┬─────────────────────┬────────┬────────┤
│ Key  │ Revision │ Op  │ Created             │ Length │ Value  │
├──────┼──────────┼─────┼─────────────────────┼────────┼────────┤
│ Key1 │        3 │ PUT │ 2025-02-07 13:16:45 │ 6      │ Value3 │
│ Key1 │        4 │ PUT │ 2025-02-07 13:17:05 │ 6      │ Value4 │
│ Key1 │        5 │ PUT │ 2025-02-07 13:33:51 │ 6      │ Value5 │
╰──────┴──────────┴─────┴─────────────────────┴────────┴────────╯

$ nats kv revert Bucket1 Key1 3
Revision: 3

Value3

? Really revert to revision 3 Yes
╭───────────────────────────────────────────────────────────────╮
│                   History for Bucket1 > Key1                  │
├──────┬──────────┬─────┬─────────────────────┬────────┬────────┤
│ Key  │ Revision │ Op  │ Created             │ Length │ Value  │
├──────┼──────────┼─────┼─────────────────────┼────────┼────────┤
│ Key1 │        4 │ PUT │ 2025-02-07 13:17:05 │ 6      │ Value4 │
│ Key1 │        5 │ PUT │ 2025-02-07 13:33:51 │ 6      │ Value5 │
│ Key1 │        6 │ PUT │ 2025-02-07 13:38:09 │ 6      │ Value3 │
╰──────┴──────────┴─────┴─────────────────────┴────────┴────────╯

Sweet! You can see the current Revision 6 has the value of Revision 3 like we asked!

Ok this was a doozy. We're not finished yet. Continue on to Part 4 of our journey as we continue our adventures with the NATS JetStream KV Store CLI!

Adventure: Building with NATS Jetstream KV Store -Part 2

Richard — Fri, 07 Feb 2025 06:31:23 +0000

Welcome back!

As you already know, this is my adventure series on the NATS JetStream Key/Value Store!

In Part 2, we continue our journey into the uncharted territories of distributed messaging. Imagine us as astronauts exploring the cosmos of JetStream - yes, that's totally us! Let's dive in right where we left off in Part 1.

Where Did We Leave Off?

In Part 1, we got the NATS CLI and NATS Server up and running with JetStream. If you missed it, don't worry - just refer back to Part 1.

Now, let's explore what we can do with the CLI

Meet your best Friend: The -h Flag. The -h flag provides guidance for commands at various levels. Start at the top level to explore commands for multiple parts of NATS.

Let's try it.

$ nats -h

usage: nats [<flags>] <command> [<args> ...]

NATS Utility

NATS Server and JetStream administration.

See '**nats cheat**' for a quick cheatsheet of commands

Commands:
  account    Account information and status
  bench      Benchmark utility
  consumer   JetStream Consumer management
  context    Manage nats configuration contexts
  errors     Error code documentation
  events     Show Advisories and Events
  kv         Interacts with a JetStream based Key-Value store
  latency    Perform latency tests between two NATS servers
  micro      Micro Services discovery and management
  object     Interacts with a JetStream based Object store
  publish    Generic data publish utility
  request    Generic request-reply request utility
  reply      Generic service reply utility
  rtt        Compute round-trip time to NATS server
  schema     Schema tools
  server     Server information
  stream     JetStream Stream management
  subscribe  Generic subscription client

Global Flags:
  -h, --help                    Show context-sensitive help
      --version                 Show application version.
  -s, --server=URL              NATS server urls ($NATS_URL)
      --user=USER               Username or Token ($NATS_USER)
      --password=PASSWORD       Password ($NATS_PASSWORD)
      --connection-name=NAME    Nickname to use for the underlying NATS Connection
      --creds=FILE              User credentials ($NATS_CREDS)
      --nkey=FILE               User NKEY ($NATS_NKEY)
      --tlscert=FILE            TLS public certificate ($NATS_CERT)
      --tlskey=FILE             TLS private key ($NATS_KEY)
      --tlsca=FILE              TLS certificate authority chain ($NATS_CA)
      --[no-]tlsfirst           Perform TLS handshake before expecting the server greeting
      --timeout=DURATION        Time to wait on responses from NATS ($NATS_TIMEOUT)
      --socks-proxy=PROXY       SOCKS5 proxy for connecting to NATS server
                                ($NATS_SOCKS_PROXY)
      --js-api-prefix=PREFIX    Subject prefix for access to JetStream API
      --js-event-prefix=PREFIX  Subject prefix for access to JetStream Advisories
      --js-domain=DOMAIN        JetStream domain to access
      --inbox-prefix=PREFIX     Custom inbox prefix to use for inboxes
      --colors=SCHEME           Sets a color scheme to use ($NATS_COLOR)
      --context=NAME            Configuration context ($NATS_CONTEXT)
      --trace                   Trace API interactions
      --no-context              Disable the selected context

Ok that's a lot. There's commands and flags in there. We will go over a lot of them in another adventure. Let's focus on the commands we want. You see we can use nats cheat to get a quick glimpse of the commands available to us.

$ nats cheat

Available Cheats:

    account
    bench
    consumer
    contexts
    errors
    events
    kv
    latency
    obj
    pub
    reply
    schemas
    server
    stream
    sub

As you can see, there’s a lot to explore! However, for this adventure, we’re focusing solely on the JetStream Key/Value Store. This would be kv for us. Don’t worry — there will be another adventure dedicated entirely to the CLI and its many features.

Understanding the Key-Value Store

Okay, let's break down this Key/Value Store thing, locker room style. It's not rocket science really.

KV Store

Think of this like a building filled with different Locker rooms or "Buckets". Each Locker room might have it's own name like "Team Awesome's Lockers," "The Losers' Lockers" or what not. Hopefully not that last one. Each Locker room can also have it's own setup or configuration.

Bucket

Think of this as a specific locker room like "Team Awesome's Lockers". It's a way to organize your stuff and contains a bunch of "lockers" which could be considered Key/Value pairs.

Key

This is like the number on a locker. It's unique, and helps us find our stuff.

Value

This is the actual stuff inside the locker. Your sweaty gym socks, your lucky rabbit's foot, or maybe even that half-eaten protein bar you forgot about. It's the data you're storing.

So there it is. It's basically like a Map!

So we will break this down into sections:

The KV Store
Buckets
Keys/Values

KV Store

Let's start by seeing what we can do now that we're using the kv command for the KV Store.

$ nats kv -h

usage: nats kv <command> [<args> ...]

Interacts with a JetStream based Key-Value store

The JetStream Key-Value store uses streams to store key-value pairs for an indefinite period or a per-bucket configured TTL.

Subcommands:
  kv add      Adds a new KV Store Bucket
  kv put      Puts a value into a key
  kv get      Gets a value for a key
  kv create   Puts a value into a key only if the key is new or it's last operation was a delete
  kv update   Updates a key with a new value if the previous value matches the given revision
  kv del      Deletes a key or the entire bucket
  kv purge    Deletes a key from the bucket, clearing history before creating a delete marker
  kv history  Shows the full history for a key
  kv revert   Reverts a value to a previous revision using put
  kv info     View the status of a KV store
  kv watch    Watch the bucket or a specific key for updated
  kv ls       List available buckets or the keys in a bucket
  kv compact  Reclaim space used by deleted keys

Global Flags:
  -h, --help                    Show context-sensitive help
      --version                 Show application version.
  -s, --server=URL              NATS server urls ($NATS_URL)
      --user=USER               Username or Token ($NATS_USER)
      --password=PASSWORD       Password ($NATS_PASSWORD)
      --connection-name=NAME    Nickname to use for the underlying NATS Connection
      --creds=FILE              User credentials ($NATS_CREDS)
      --nkey=FILE               User NKEY ($NATS_NKEY)
      --tlscert=FILE            TLS public certificate ($NATS_CERT)
      --tlskey=FILE             TLS private key ($NATS_KEY)
      --tlsca=FILE              TLS certificate authority chain ($NATS_CA)
      --[no-]tlsfirst           Perform TLS handshake before expecting the server greeting
      --timeout=DURATION        Time to wait on responses from NATS ($NATS_TIMEOUT)
      --socks-proxy=PROXY       SOCKS5 proxy for connecting to NATS server ($NATS_SOCKS_PROXY)
      --js-api-prefix=PREFIX    Subject prefix for access to JetStream API
      --js-event-prefix=PREFIX  Subject prefix for access to JetStream Advisories
      --js-domain=DOMAIN        JetStream domain to access
      --inbox-prefix=PREFIX     Custom inbox prefix to use for inboxes
      --colors=SCHEME           Sets a color scheme to use ($NATS_COLOR)
      --context=NAME            Configuration context ($NATS_CONTEXT)
      --trace                   Trace API interactions
      --no-context              Disable the selected context

Wow. Ok. There’s quite a few commands there but it seems like there’s two for the KV Store itself — info and ls

info says it will give us the status of the KV Store.

$ nats kv info

nats: error: no KV buckets found

No buckets found? We’ll I guess that makes sense because we never created one! Let’s just check to be sure. We can list the buckets of a KV Store with ls

$ nats kv ls

No Key-Value buckets found

Yep. Not a bucket in sight! So how do we create a bucket?

Creating Buckets

As we stated earlier a Bucket is like a locker room for your lockers (KV Pairs). So let’s get on with it and create a locker room — a Bucket! Let's create a Bucket called Bucket1.

$ nats kv add Bucket1

Information for Key-Value Store Bucket Bucket1 created 2025-01-18T20:18:27-05:00

Configuration:

          Bucket Name: Bucket1
         History Kept: 1
        Values Stored: 0
           Compressed: false
   Backing Store Kind: JetStream
          Bucket Size: 0 B
  Maximum Bucket Size: unlimited
   Maximum Value Size: unlimited
          Maximum Age: unlimited
     JetStream Stream: KV_Bucket1
              Storage: File

Cluster Information:

                 Name:
               Leader: NDJ4PFQB5RVJXFDKC6G7ZZRDBEH3M4OMEUMDQFXJE5BFNSALQLAHMTEV

You will see information on the bucket we just created.

# Bucket Name: Bucket1                # Name of the Key-Value bucket.
# History Kept: 1                     # Number of historical versions retained per key.
# Values Stored: 0                    # Current number of keys (lockers) in the bucket.
# Compressed: false                   # Indicates if data compression is enabled for this bucket.
# Backing Store Kind: JetStream       # Storage backend used (JetStream in this case).
# Bucket Size: 0 B                    # Total size of the bucket's stored data.
# Maximum Bucket Size: unlimited      # Maximum storage size allowed for the bucket (no limit here).
# Maximum Value Size: unlimited       # Maximum size for a single key's value (no limit here).
# Maximum Age: unlimited              # Maximum time a key-value pair is retained (no expiration here).
# JetStream Stream: KV_Bucket1        # JetStream stream backing this Key-Value bucket.
# Storage: File                       # Type of storage used (file-based in this case).

Let's go again!

$ nats kv add Bucket2

Information for Key-Value Store Bucket Bucket2 created 2025-01-18T20:18:35-05:00

Configuration:

          Bucket Name: Bucket2
         History Kept: 1
        Values Stored: 0
           Compressed: false
   Backing Store Kind: JetStream
          Bucket Size: 0 B
  Maximum Bucket Size: unlimited
   Maximum Value Size: unlimited
          Maximum Age: unlimited
     JetStream Stream: KV_Bucket2
              Storage: File

Cluster Information:

                 Name:
               Leader: NDJ4PFQB5RVJXFDKC6G7ZZRDBEH3M4OMEUMDQFXJE5BFNSALQLAHMTEV

Now let's try nats kv info again.

$ nats kv info

You should get a menu - you can select which bucket you want info for.

? Select a Bucket  [Use arrows to move, type to filter]
> Bucket1
  Bucket2

Let's pick Bucket1.

Information for Key-Value Store Bucket Bucket1 created 2025-01-18T20:18:27-05:00

Configuration:

          Bucket Name: Bucket1
         History Kept: 1
        Values Stored: 0
           Compressed: false
   Backing Store Kind: JetStream
          Bucket Size: 0 B
  Maximum Bucket Size: unlimited
   Maximum Value Size: unlimited
          Maximum Age: unlimited
     JetStream Stream: KV_Bucket1
              Storage: File

Cluster Information:

                 Name:
               Leader: NDJ4PFQB5RVJXFDKC6G7ZZRDBEH3M4OMEUMDQFXJE5BFNSALQLAHMTEV

As you can see, you can always access information for various Buckets. Each Bucket can have its own configuration with different properties. You can define these properties during creation using flags.

Let’s create a bucket using the compress flag!

$ nats kv add Bucket3 --compress

Information for Key-Value Store Bucket Bucket3 created 2025-01-18T22:40:43-05:00

Configuration:

          Bucket Name: Bucket3
         History Kept: 1
        Values Stored: 0
           Compressed: true
   Backing Store Kind: JetStream
          Bucket Size: 0 B
  Maximum Bucket Size: unlimited
   Maximum Value Size: unlimited
          Maximum Age: unlimited
     JetStream Stream: KV_Bucket3
              Storage: File

Cluster Information:

                 Name:
               Leader: NDJ4PFQB5RVJXFDKC6G7ZZRDBEH3M4OMEUMDQFXJE5BFNSALQLAHMTEV

What does the compressed flag do? If it’s not configured then the bucket is not using internal compression for its stored data. Data is stored as-is in the underlying stream (uncompressed).

If enabled then compression is enabled for the data stored in the underlying stream, which can reduce disk usage at the cost of slightly higher CPU usage during compression and decompression.

Pretty neat! As you can see there’s a few other configuration options that come with their own flags — but for now let’s keep going.

Let’s try to list all the Buckets again…

$ nats kv ls

╭───────────────────────────────────────────────────────────────────────────╮
│                             Key-Value Buckets                             │
├─────────┬─────────────┬─────────────────────┬──────┬────────┬─────────────┤
│ Bucket  │ Description │ Created             │ Size │ Values │ Last Update │
├─────────┼─────────────┼─────────────────────┼──────┼────────┼─────────────┤
│ Bucket1 │             │ 2025-01-19 02:55:03 │ 0 B  │ 0      │ never       │
│ Bucket2 │             │ 2025-01-19 02:55:05 │ 0 B  │ 0      │ never       │
│ Bucket3 │             │ 2025-01-19 02:55:31 │ 0 B  │ 0      │ never       │
╰─────────┴─────────────┴─────────────────────┴──────┴────────┴─────────────╯

Boom! There they are!

There’s a lot to explore when it comes to creating buckets, but we’ll save that for a deep dive later.

Reading from Buckets

Let’s check the keys in a bucket and make sure they’re empty.

$ nats kv ls Bucket1

No keys found in bucket

This ones obvious. We haven’t created any keys yet!

Bucket Update

Alrighty, how do we update a bucket. Well — it’s not that simple. The bucket’s configuration, such as TTL, history, maximum size, and compression settings, is fixed at the time of creation.

Why Can’t a Bucket Be Modified?

This behavior ensures:

Consistency: Prevents unexpected changes that could affect how data is stored or retrieved.
Integrity: Protects existing data from being impacted by configuration changes like reduced history or TTL adjustments.
Simplicity: Keeps the design predictable and easy to reason about.

Alright cool. Three buckets seems like too many so let’s get rid of one.

What you can do is export the data and recreate the bucket, a process that your team would typically have workflows and protocols for. This isn’t something that would be done frequently if at all. Something my dad used to tell me — the 5 P’s.

"Proper planning prevents piss poor performance!"

Bucket Delete

Well I don’t like Bucket3 so I want delete him or her. Let’s just get a quick idea of what happens.

All Keys and Values Are Removed — Every key, its values, and history stored in the bucket are permanently deleted. This action cannot be undone, so proceed with caution.
Underlying JetStream Stream Is Deleted — A KV bucket in NATS JetStream is backed by a JetStream stream. When you delete the bucket, the corresponding stream is also deleted.
Storage Space Is Reclaimed — All disk space previously used by the bucket is freed, making it available for other operations. Audit Trails Are Lost — Unlike individual key deletions or purges, deleting a bucket does not retain any markers or history. The bucket and all its contents are entirely erased.

Sorry bucket 3!

$ nats kv del Bucket3

? Delete bucket Bucket3? Yes

Let's make sure it's gone.

$ nats kv ls

╭───────────────────────────────────────────────────────────────────────────╮
│                             Key-Value Buckets                             │
├─────────┬─────────────┬─────────────────────┬──────┬────────┬─────────────┤
│ Bucket  │ Description │ Created             │ Size │ Values │ Last Update │
├─────────┼─────────────┼─────────────────────┼──────┼────────┼─────────────┤
│ Bucket1 │             │ 2025-01-18 20:18:27 │ 0 B  │ 0      │ never       │
│ Bucket2 │             │ 2025-01-18 20:18:35 │ 0 B  │ 0      │ never       │
╰─────────┴─────────────┴─────────────────────┴──────┴────────┴─────────────╯

Yep! A goner!

Deleting a Bucket isn’t something that would typically be done. While there may be specific scenarios where it’s necessary, deleting a Bucket is almost akin to deleting an entire database. In such cases, protocols and workflows should be in place to manage the process — much like updating a Bucket.

It’s worth noting that NATS keeps track of history for operations like deleting a Bucket, but diving into those details is beyond our current scope.

So far, we’ve explored how to create Bucket with configurations, check their information, and delete them. Neat! Now, it’s time to dive into actually using Buckets. Let’s explore how keys work.

I think we’ve done enough here for now; so let’s skip on ahead to Part 3 with keys!

Adventure: Building with NATS Jetstream KV Store -Part 1

Richard — Fri, 07 Feb 2025 00:44:52 +0000

Welcome!

Welcome to my adventure series on the NATS JetStream Key/Value Store!
This series is here to help complete beginners, step by step - no prior knowledge needed (really, trust me, I didn't have much when I started either!).

No one begins as an expert - that's the beauty of learning! By the end of this journey, you'll not only grasp the basics of the NATS JetStream KV Store but also build a fully functional multiplayer Tic-Tac-Toe game, capable of handling multiple concurrent games.

It will end up looking something like this.

This isn't going to be a comprehensive deep dive - if that's what you're looking for, Synadia has a ton of great videos that cover NATS as deep as you want to go.

No - this is for someone like me: someone who's occasionally a bit lazy and appreciates being spoon-fed the basics. Is that a bad thing or a hidden virtue? I'll let you decide. We're going for a "getting-your-feet-wet" practical usage of the KV Store.

How did we get here?

For quite sometime I didn't even know what NATS was, I had seen it in certain books I was reading or on a YouTube video the algorithm decided to toss at me yet it wasn't until a very talented coworker had made me aware of it. He was able to build very impressive applications extremely fast, and I didn't understand how. He was humble and would simply say:

"Everyone just makes things more complicated than they have to be."

"You're probably just over-complicating it."

I didn't believe him. How did this guy move so quick. Was he one of the legendary 10x programmers we all hear about? I don't know; maybe (yes) - but he did let me in on something.

"Sometimes, certain tools are just better than others."
(We can come back to this one.)

Well, what tools? I want that kind of superpower! One tool he often raved about was NATS, so I finally decided to see what all the fuss was about.

Alright come on! What the heck is NATS?!

Alright let's cut to the chase

"NATS is a connective technology built for the ever increasingly hyper-connected world. It is a single technology that enables applications to securely communicate across any combination of cloud vendors, on-premise, edge, web and mobile, and devices."

Ok, so…what does that mean??

NATS is a single technology composed of various parts that can work in cohesion but you can use parts like Jetstream on their own. It's powerful so just boiling it down to a little list wouldn't do it justice. However; I'm still going to do that; for US!

NATS Core

NATS Core is… well the Core. The fundamental backbone of NATS. There's a lot there but let's try to boil it down.
NATS Core is like live TV or a live broadcast - offering Publish/Subscribe and Request/Reply patterns with an ephemeral nature. If you're not tuned in when the message is broadcast, you miss it. There's no recording, no rewind - just real-time communication. We'll dive deeper into NATS Core in another adventure.

NATS JetStream

NATS Jetstream is built on top of NATS Core.
NATS JetStream is like a DVR or streaming service for your messaging system. It provides features such as Streams, Consumers, an Object Store, and, most importantly for our exploration, the Key Value Store.

Think of the K/V Store like a locker system where you can store and retrieve small pieces of information by key (like storing a favorite recipe or settings for your TV).

Key Takeaways

NATS Core is fast, lightweight, and ideal for real-time communication where persistence isn't needed.
NATS JetStream adds persistence, replay, and storage capabilities, making it ideal for use cases requiring message durability or more extensive data management.

There's a lot more to it but we'll just be succinct because we have so many other adventures to go on!

When can we start?

Right now! Let's do it! We need to get setup to use Jetstream. Since we'll be coding in Go later, we'll install the NATS CLI using Go as well. Here's the lowdown on getting Go, the NATS CLI, and the NATS Server up and running on a Debian Linux system:

Install Go

Download the Go Archive

Head over to the official Go downloads page. Find the latest stable release for Linux (it will be a .tar.gz file, probably something like go1.XX.linux-amd64.tar.gz). Copy the link to that file.

Open a Terminal:

Fire up your terminal.

Download the Archive (using `wget`)

Paste the link you copied into the following command, replacing the example filename with the actual filename:

$ wget https://go.dev/dl/go1.XX.linux-amd64.tar.gz

Extract the Archive

$ sudo tar -xzvf go1.XX.linux-amd64.tar.gz -C /usr/local

(This extracts Go to /usr/local which is a pretty standard location).

Set Up Your Path

You need to add Go's bin directory to your system's PATH. Open your ~/.bashrc file (or ~/.zshrc if you use Zsh) with a text editor:

$ nano ~/.bashrc  # Or vi ~/.bashrc, or gedit ~/.bashrc, etc.

Add the Path

Add the following line to the end of the file:

$ export PATH=$PATH:/usr/local/go/bin

Save and Source

Save the file and then run:

$ source ~/.bashrc

Verify the Installation

Check that Go is installed correctly by running:

$ go version

Install NATS CLI

Download the NATS CLI binary

$ wget https://github.com/nats-io/natscli/releases/latest/download/nats-linux-amd64

Make the binary executable

$ chmod +x nats-linux-amd64

Move the binary to a directory in your PATH

$ sudo mv nats-linux-amd64 /usr/local/bin/nats

Verify installation

$ nats --version

Install NATS Server

Download the NATS Server binary

$ wget https://github.com/nats-io/nats-server/releases/latest/download/nats-server-linux-amd64

Make the binary executable

$ chmod +x nats-server-linux-amd64

Move the binary to a directory in your PATH

$ sudo mv nats-server-linux-amd64 /usr/local/bin/nats-server

Verify installation

$ nats-server --version

Start NATS Server

Run the server:

$ nats-server

Sweet. It looks like we're cooking!

So let's do some stuff!

Open your terminal and locate the nats-server binary we installed.

Follow along with me!

$ ./nats-server 

[26351] 2025/01/17 23:42:47.658293 [INF] Starting nats-server
[26351] 2025/01/17 23:42:47.658708 [INF]   Version:  2.10.20                                                    
[26351] 2025/01/17 23:42:47.658719 [INF]   Git:      [7140387]                                                  
[26351] 2025/01/17 23:42:47.658729 [INF]   Name:     XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX   
[26351] 2025/01/17 23:42:47.658739 [INF]   ID:       XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX   
[26351] 2025/01/17 23:42:47.660565 [INF] Listening for client connections on 0.0.0.0:XXXX                       
[26351] 2025/01/17 23:42:47.661437 [INF] Server is ready

# You will see that the server is up and ready.

# Info will be displayed about our NATS Server.

# Version:  2.10.20        # Name of the Key-Value bucket.
# Git:      [7140387]      # Git Commit Hash of the nats-server source code
# Name:                    # NATS Server Name.
# ID:                      # NATS Server ID
# Listening for ...        # Address and Port nats-server is listening on. 
#                          # - Listening on all available network interfaces

Ok so NATS Server is running, noice! Only one issue, we're not running with Jetstream. You can tell by opening another terminal window and checking.

Let's check for more information on our server.

$ nats account info

Account Information

                      User: 
                   Account: $G
                   Expires: never
                 Client ID: 5
                 Client IP: 127.0.0.1
                       RTT: 87µs
         Headers Supported: true
           Maximum Payload: 1.0 MiB
             Connected URL: nats://127.0.0.1:4222
         Connected Address: 127.0.0.1:4222
       Connected Server ID: NDQH5BXP4G6HACAE3VFZLD6OUYJB6GF3YEUP3S25YA4J34U2RU7SJ4DK
  Connected Server Version: 2.10.20
            TLS Connection: no
    Could not obtain account information:  nats: jetstream not enabled

Notice that it tells us that Jetstream is not enabled. Oops! Ok - no biggie. Just go to the terminal where NATS Server is running and CTRL-C. Let's try this again!

$ ./nats-server -jetstream or -js

# You'll see something like this now.

[27511] 2025/01/17 23:59:29.453968 [INF] Starting nats-server
[27511] 2025/01/17 23:59:29.454436 [INF]   Version:  2.10.20
[27511] 2025/01/17 23:59:29.454448 [INF]   Git:      [7140387]
[27511] 2025/01/17 23:59:29.454458 [INF]   Name:     NAI6RRCXFGU7GESGBIZJSXHNU2N2UGTOB6BQYEOZDKW2CP76BRNZXMK3
[27511] 2025/01/17 23:59:29.454474 [INF]   Node:     3BBAzCdl
[27511] 2025/01/17 23:59:29.454483 [INF]   ID:       NAI6RRCXFGU7GESGBIZJSXHNU2N2UGTOB6BQYEOZDKW2CP76BRNZXMK3
[27511] 2025/01/17 23:59:29.456007 [INF] Starting JetStream
[27511] 2025/01/17 23:59:29.456570 [INF]     _ ___ _____ ___ _____ ___ ___   _   __  __
[27511] 2025/01/17 23:59:29.456598 [INF]  _ | | __|_   _/ __|_   _| _ \ __| /_\ |  \/  |
[27511] 2025/01/17 23:59:29.456613 [INF] | || | _|  | | \__ \ | | |   / _| / _ \| |\/| |
[27511] 2025/01/17 23:59:29.456631 [INF]  \__/|___| |_| |___/ |_| |_|_\___/_/ \_\_|  |_|
[27511] 2025/01/17 23:59:29.456651 [INF] 
[27511] 2025/01/17 23:59:29.456669 [INF]          https://docs.nats.io/jetstream
[27511] 2025/01/17 23:59:29.456680 [INF] 
[27511] 2025/01/17 23:59:29.456692 [INF] ---------------- JETSTREAM ----------------
[27511] 2025/01/17 23:59:29.456709 [INF]   Max Memory:      11.53 GB
[27511] 2025/01/17 23:59:29.456730 [INF]   Max Storage:     281.91 GB
[27511] 2025/01/17 23:59:29.456751 [INF]   Store Directory: "/tmp/nats/jetstream"
[27511] 2025/01/17 23:59:29.456771 [INF] -------------------------------------------
[27511] 2025/01/17 23:59:29.457933 [INF] Listening for client connections on 0.0.0.0:4222
[27511] 2025/01/17 23:59:29.458739 [INF] Server is ready

Ok - we see Jetstream in there! Let's try the account command again.

$ nats account info

Account Information

                           User: 
                        Account: $G
                        Expires: never
                      Client ID: 350
                      Client IP: 127.0.0.1
                            RTT: 122µs
              Headers Supported: true
                Maximum Payload: 1.0 MiB
                  Connected URL: nats://127.0.0.1:4222
              Connected Address: 127.0.0.1:4222
            Connected Server ID: NDJ4PFQB5RVJXFDKC6G7ZZRDBEH3M4OMEUMDQFXJE5BFNSALQLAHMTEV
       Connected Server Version: 2.10.20
                 TLS Connection: no

JetStream Account Information:

Account Usage:

                        Storage: 0 B
                         Memory: 0 B
                        Streams: 3
                      Consumers: 0

Account Limits:

            Max Message Payload: 1.0 MiB

  Tier: Default:

      Configuration Requirements:

        Stream Requires Max Bytes Set: false
         Consumer Maximum Ack Pending: Unlimited

      Stream Resource Usage Limits:

                               Memory: 0 B of Unlimited
                    Memory Per Stream: Unlimited
                              Storage: 0 B of Unlimited
                   Storage Per Stream: Unlimited
                              Streams: 3 of Unlimited
                            Consumers: 0 of Unlimited

Wow. Ok. There's a ton of new information about Jetstream. We will go into this in another adventure. For now let's just keep pushing!

Sorry I had to trick you like that but look - we're learning! NATS Server is now up and running with Jetstream! It kind of just works.
Anyhow, I hate to say it but I feel like we're rather low down on this page and nobody wants to scroll this far! So we shall continue our adventure in Part 2!

See ya there!