DEV Community: IamKhan

How to implement RBAC in Go

IamKhan — Tue, 30 Jun 2026 17:21:51 +0000

My intention with this article is to show how I'd implement role-based access control (RBAC) if I had to -
in the hope that it acts as a guide for when you need to implement something similar in your projects. I am writing this implementation in go but the concepts discussed are practically universal and can be replicated in any programming language you choose.

This article isn't for absolute beginners, you'll need to be familiar with basic concepts in golang and sql to follow along.

Project Description
Database Schemas
Seeding the Database
Initializing the Project
Adding Entities
Implementing Users
Implementing Permissions
Implementing Authorization
Implementing Posts
Adding Routes
Adding a Cache

Project Description

For the purpose of this article, we will assume we have a bunch of blog posts and we want to define permissions for certain operations based on the following user roles:

viewer (can view all blog posts)
editor (can view, create, edit and delete his/her own blog post)
admin (gets all privileges)

Before we jump in, I'll like to note that this is an article about authorization not authentication and so the parts of the code we will write that should contain the logic for authentication will be omitted. You should fill them out yourself while you follow along.

By the end of this lesson - as a bonus, we'll add an in-memory cache to avoid performing database calls every time we need to access restricted resources.

Database Schemas

As indicated in the previous section, we'll need a table for posts. Posts need authors therefore we'll add a table for users as well.

In your migration file add the following:

CREATE TABLE IF NOT EXISTS users (
    id INT generated always as identity,
    name TEXT NOT NULL,
    email TEXT NOT NULL UNIQUE,
    password BYTEA NOT NULL,
    created_at TIMESTAMPTZ DEFAULT current_timestamp,
    PRIMARY KEY(id)
);

CREATE TABLE IF NOT EXISTS posts (
    id INT generated always as identity,
    title TEXT NOT NULL,
    content TEXT NOT NULL,
    slug TEXT NOT NULL,
    author_id INT,
    created_at TIMESTAMPTZ DEFAULT current_timestamp,
    PRIMARY KEY(id),
    FOREIGN KEY (author_id) REFERENCES users(id) ON DELETE SET NULL
);

We've created users and posts tables. The posts table has a foreign key constraint on its author_id property that references the users table

Now that we have that out of the way, we need to create schemas for roles and permissions. In your migration file add the following:

-- ...

CREATE TABLE IF NOT EXISTS roles (
    id INT generated always as identity,
    role TEXT,
    description TEXT,
    PRIMARY KEY(id)
);

CREATE TABLE IF NOT EXISTS user_roles (
    role_id INT,
    user_id INT,
    PRIMARY KEY (role_id, user_id),
    FOREIGN KEY (role_id) REFERENCES roles(id) ON DELETE CASCADE,
    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
);

CREATE TABLE IF NOT EXISTS permissions (
    id INT generated always as identity,
    name TEXT,
    PRIMARY KEY(id)
);

CREATE TABLE IF NOT EXISTS role_permission (
    permission_id INT,
    role_id INT,
    PRIMARY KEY(permission_id, role_id),
    FOREIGN KEY (role_id) REFERENCES roles(id) ON DELETE CASCADE,
    FOREIGN KEY (permission_id) REFERENCES permissions(id) ON DELETE CASCADE
);

Here we added a couple of tables - roles, user_roles, permissions, role_permission. user_roles and role_permission are linking tables that connect users to their roles in the case of user_roles and a role to its permissions in the case of role_permission.

Seeding the Database

We need to seed our roles, permissions and role_permission tables with the necessary data. In your migration file add:

-- ...

INSERT INTO roles (role, description) VALUES
    ('viewer', 'can view all blog posts'),
    ('editor', 'can view, create, edit and delete a blog post'),
    ('admin', 'all privileges');

INSERT INTO permissions (name) VALUES
    ('users:read'),
    ('users:update'),
    ('posts:read'),
    ('posts:create'),
    ('posts:update'),
    ('posts:delete');

INSERT INTO role_permission (permission_id, role_id) VALUES
    ((SELECT id FROM permissions WHERE name = 'posts:read'), (SELECT id FROM roles WHERE role = 'viewer')),
    ((SELECT id FROM permissions WHERE name = 'posts:read'), (SELECT id FROM roles WHERE role = 'editor')),
    ((SELECT id FROM permissions WHERE name = 'posts:create'), (SELECT id FROM roles WHERE role = 'editor')),
    ((SELECT id FROM permissions WHERE name = 'posts:update'), (SELECT id FROM roles WHERE role = 'editor')),
    ((SELECT id FROM permissions WHERE name = 'posts:delete'), (SELECT id FROM roles WHERE role = 'editor')),
    ((SELECT id FROM permissions WHERE name = 'posts:read'), (SELECT id FROM roles WHERE role = 'admin')),
    ((SELECT id FROM permissions WHERE name = 'posts:create'), (SELECT id FROM roles WHERE role = 'admin')),
    ((SELECT id FROM permissions WHERE name = 'posts:update'), (SELECT id FROM roles WHERE role = 'admin')),
    ((SELECT id FROM permissions WHERE name = 'posts:delete'), (SELECT id FROM roles WHERE role = 'admin')),
    ((SELECT id FROM permissions WHERE name = 'users:read'), (SELECT id FROM roles WHERE role = 'admin')),
    ((SELECT id FROM permissions WHERE name = 'users:update'), (SELECT id FROM roles WHERE role = 'admin'));

Initializing the Project

Initialize your go project with the command go mod init demoblog and create an entry file main.go.
In your entry file add the following:

package main

import (
    "context"
    "flag"
    "fmt"
    "log"
    "net/http"
    "os/signal"
    "syscall"
    "time"
)

type config struct {
    port int
}

type application struct {
    cfg     config
    handler func() http.Handler
}

func (app *application) mount() {
    app.handler = func() http.Handler {
        mux := http.NewServeMux()
        return mux
    }
}

func (app *application) run(ctx context.Context) error {
    app.mount()

    serv := &http.Server{
        Addr:    fmt.Sprintf(":%d", app.cfg.port),
        Handler: app.handler(),
    }

    select {
    case err := <-app.serve(serv):
        return err
    case <-ctx.Done():
        return app.shutdown(serv)
    }
}

func (app *application) serve(serv *http.Server) <-chan error {
    ch := make(chan error, 1)
    go func() {
        ch <- serv.ListenAndServe()
    }()
    return ch
}

func (app *application) shutdown(serv *http.Server) error {
    ctx := context.Background()
    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
    defer cancel()
    return serv.Shutdown(ctx)
}

func main() {
    var cfg config

    flag.IntVar(&cfg.port, "port", 3000, "application port")
    flag.Parse()

    ctx := context.Background()
    ctx, cancel := signal.NotifyContext(ctx, syscall.SIGTERM, syscall.SIGINT)
    defer cancel()

    app := &application{
        cfg: cfg,
    }

    if err := app.run(ctx); err != nil {
        log.Fatal(err)
    }
}

Here we have created an http server that runs on port 3000. To start your server, in your terminal run the command go run main.go. If for some reason you've got another application running on port 3000, you can add a flag to run your server on another port like so - go run main.go --port=3001

Adding Entities

Before we get to writing repository and handler methods, let's create a couple of structs that map directly to properties of the tables in our database. We have a users table so we need a User struct - let's write our struct.

In your working directory add an internal folder. We'll be adding packages to this folder. In internal create a package called entities and add a user.go file. In user.go add the following:

package entities

import "time"

type User struct {
    ID        int       `db:"id" json:"id"`
    Name      string    `db:"name" json:"name"`
    Email     string    `db:"email" json:"email"`
    Password  []byte    `db:"password" json:"-"`
    CreatedAt time.Time `db:"created_at" json:"created_at"`
}

We have a posts table so let's create a post.go file in the same package and add the following:

package entities

import "time"

type Post struct {
    ID        int       `db:"id" json:"id"`
    Title     string    `db:"title" json:"title"`
    Content   string    `db:"content" json:"content"`
    Slug      string    `db:"slug" json:"slug"`
    AuthorID  int       `db:"author_id" json:"author_id"`
    CreatedAt time.Time `db:"created_at" json:"created_at"`
}

Let's do the same for permissions. Create a permission.go file in the same package and add the following:

package entities

import "slices"

const (
    PostsRead   = "posts:read"
    PostsWrite  = "posts:create"
    PostsUpdate = "posts:update"
    PostsDelete = "posts:delete"
    UsersRead   = "users:read"
    UsersUpdate = "users:update"
)

type Permissions []string

func (p Permissions) Can(permission string) bool {
    return slices.Contains(p, permission)
}

Permissions is a named type that has a method - Can. Can checks if the permission passed to the method as an argument is contained in the slice of permissions it holds

Implementing Users

Before we write any code, let's go over what we need to do. We need to create a user and assign said user its default role. In our example viewer is the default role for new users.

If you recall what we did in our sql schemas, we have separate tables to store user information - users and their role - user_roles. To successfully add a user we'll need to perform two operations - add a user and add the user's role. We also don't want to do both database writes in two separate actions. This is the exact problem transactions solve.
By definition a database transaction is a single logical unit of work made up of multiple operations.

To execute database queries, we need to add a postgres driver to our project. pgx is the recommended one by consensus so we'll use it. To add it as a dependency to your project run the command go get github.com/jackc/pgx/v5 in your terminal. When the installation is done, create a users package in internal then add repository and handler files.

In your internal/users/repository.go file add the following:

package users

import (
    "context"

    "github.com/jackc/pgx/v5"
    "github.com/jackc/pgx/v5/pgconn"

    "demoblog/internal/entities"
)

type dbtx interface {
    Query(ctx context.Context, query string, args ...any) (pgx.Rows, error)
    QueryRow(ctx context.Context, query string, args ...any) pgx.Row
    Exec(ctx context.Context, query string, args ...any) (pgconn.CommandTag, error)
}

type Repository interface {
    CreateUser(ctx context.Context, param CreateUserParam) (*entities.User, error)
    ListUsers(ctx context.Context) ([]entities.User, error)
    UpdateUserRole(ctx context.Context, id int) error
}

type repository struct {
    db dbtx
    dB *pgx.Conn
}

func NewRepository(db *pgx.Conn) *repository {
    return &repository{
        db: db,
        dB: db,
    }
}

func (r *repository) withTx(db dbtx) *repository {
    return &repository{
        db: db,
        dB: r.dB,
    }
}

func execTx(ctx context.Context, db *pgx.Conn, fn func(pgx.Tx) error) error {
    tx, err := db.BeginTx(ctx, pgx.TxOptions{})
    if err != nil {
        return err
    }

    defer tx.Rollback(ctx)

    if err := fn(tx); err != nil {
        return err
    }

    return tx.Commit(ctx)
}

func (r *repository) CreateUser(ctx context.Context, param CreateUserParam) (*entities.User, error) {
    var user entities.User

    err := execTx(ctx, r.dB, func(tx pgx.Tx) error {
        var err error
        user, err = r.withTx(tx).createUser(ctx, param)
        if err != nil {
            return err
        }

        return r.withTx(tx).assignRole(ctx, user.ID)
    })
    if err != nil {
        return nil, err
    }

    return &user, nil
}

func (r *repository) createUser(ctx context.Context, param CreateUserParam) (entities.User, error) {
    query := `
  INSERT INTO users (name, email, password) VALUES (@name, @email, @password)
  RETURNING id, name, email, password, created_at;
  `
    row := r.db.QueryRow(ctx, query, pgx.NamedArgs{
        "name":     param.Name,
        "email":    param.Email,
        "password": hashPassword(param.Password),
    })

    var user entities.User

    err := row.Scan(
        &user.ID,
        &user.Name,
        &user.Email,
        &user.Password,
        &user.CreatedAt,
    )
    if err != nil {
        return user, err
    }

    return user, nil
}

func (r *repository) assignRole(ctx context.Context, id int) error {
    query := `
  INSERT INTO user_roles (user_id, role_id) VALUES
  (@user_id, (SELECT id FROM roles WHERE role = 'viewer'));
  `
    _, err := r.db.Exec(ctx, query, pgx.NamedArgs{"user_id": id})
    return err
}

func (r *repository) ListUsers(ctx context.Context) ([]entities.User, error) {
    query := `SELECT id, name, email, password, created_at FROM users;`

    rows, err := r.db.Query(ctx, query)
    if err != nil {
        return nil, err
    }

    return pgx.CollectRows(rows, pgx.RowToStructByName[entities.User])
}

func (r *repository) UpdateUserRole(ctx context.Context, id int) error {
    query := `
  UPDATE user_roles SET
    role_id = (SELECT id FROM roles WHERE role = 'editor') WHERE user_id = @id;
  `
    _, err := r.db.Exec(ctx, query, pgx.NamedArgs{"id": id})
    return err
}

func hashPassword(_ string) []byte {
    // TODO: add implementation
    return nil
}

This code snippet has quite a number of moving parts so let's talk about it. There's a repository struct, that implements the Repository interface but that isn't really all it does. It has two extra methods - createUser and assignRole. Both methods perform the operation their names describe - but they are two separate queries and we need them to happen in one call. execTx is helper function that encapsulates the logic for performing database transactions. We also have a withTx method on the repository struct that in fact returns a reference to the repository itself. This looks kinda odd but it's a nifty trick to make the methods on the struct reusable. All of this allows us perform both operations in one CreateUser call. ListUsers fetches all users from the database and UpdateUserRole updates a user's role - it basically promotes a viewer to editor.

Now let's write our handler. In internal/users/handler.go add the following:

package users

import (
    "encoding/json"
    "io"
    "net/http"
    "strconv"
)

type CreateUserParam struct {
    Name     string `json:"name" validate:"required"`
    Email    string `json:"email" validate:"required"`
    Password string `json:"password" validate:"required"`
}

type handler struct {
    repo Repository
}

func NewHandler(repo Repository) *handler {
    return &handler{
        repo: repo,
    }
}

func (h *handler) CreateUser(w http.ResponseWriter, r *http.Request) error {
    defer r.Body.Close()
    var param CreateUserParam

    b, err := io.ReadAll(r.Body)
    if err != nil {
        return err
    }

    if err := json.Unmarshal(b, &param); err != nil {
        return err
    }

    // TODO: validate params here

    user, err := h.repo.CreateUser(r.Context(), param)
    if err != nil {
        return err
    }

    // TODO: create auth tokens here

    return json.NewEncoder(w).Encode(user)
}

func (h *handler) ListUsers(w http.ResponseWriter, r *http.Request) error {
    users, err := h.repo.ListUsers(r.Context())
    if err != nil {
        return err
    }

    w.WriteHeader(200)
    return json.NewEncoder(w).Encode(users)
}

func (h *handler) EditUserRole(w http.ResponseWriter, r *http.Request) error {
    id, err := strconv.Atoi(r.PathValue("id"))
    if err != nil {
        return err
    }

    if err := h.repo.UpdateUserRole(r.Context(), id); err != nil {
        return err
    }

    w.WriteHeader(200)
    return nil
}

Here we have a CreateUserParam struct for collecting user input. The struct has the tags necessary for JSON marshalling and validation. The Repository interface exposes a CreateUser method and the handler struct has a CreateUser http handler. The http handler collects user input, "unmarshals" it into CreateUserParam and calls CreateUser from the repository to add a user to the database. The response from our repository layer is then sent back to the client. ListUsers gets all users from the database and sends them over the wire and EditUserRole makes a viewer into an editor.

Implementing Permissions

What we need to do here is fetch the permissions associated with a user from the database. At first glance it would seem as though there isn't an obvious link between users and their permissions but this isn't the case - that's why we have linking tables. Permissions have a linking table with roles and roles have a linking table with users - that's our connection. To perform this operation we need to join all the tables involved. Let's write the query.

Create a permissions package. In the package add a repository file - internal/permissions/repository.go. In your repository.go file add the following:

package permissions

import (
    "context"

    "github.com/jackc/pgx/v5"

    "demoblog/internal/entities"
)

type dbtx interface {
    Query(ctx context.Context, query string, args ...any) (pgx.Rows, error)
}

type repository struct {
    db dbtx
}

func NewRepository(db dbtx) *repository {
    return &repository{
        db: db,
    }
}

func (r *repository) GetUserPermissions(ctx context.Context, id int) (entities.Permissions, error) {
    query := `
  SELECT p.name
  FROM users u
  LEFT JOIN user_roles ur ON u.id = ur.user_id
  LEFT JOIN roles r ON ur.role_id = r.id
  LEFT JOIN role_permission rp ON r.id = rp.role_id
  LEFT JOIN permissions p ON rp.permission_id = p.id
  WHERE u.id = @id;
  `

    rows, err := r.db.Query(ctx, query, pgx.NamedArgs{"id": id})
    if err != nil {
        return nil, err
    }

    return pgx.CollectRows(rows, pgx.RowTo[string])
}

Here we have a repository struct with a GetUserPermissions method that runs a query to fetch all the permissions for a user. In practice, based on the rules we wrote in our schemas, if the id of a user who is an editor is passed to this method, it should return a slice of the following permissions - ['posts:read', posts:create', 'posts:update', 'posts:delete']

Implementing Authorization

Now that we've got our got our queries out of the way, let's add authorization to our API. We'll do this in a middleware. If you aren't familiar with what a middleware is - it's essentially a function that intercepts an HTTP request before it reaches the server's core application logic. This is a sweet spot for authorization checks. Let's write the middleware.

In internal create a middleware package and add a middleware.go file. In middleware/middleware.go add the following:

package middleware

import (
    "context"
    "log/slog"
    "net/http"

    "demoblog/internal/entities"
)

type UserRepository interface {
    GetUserByID(ctx context.Context, id int) (*entities.User, error)
}

func Authenticate(repo UserRepository) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            authorization := r.Header.Get("Authorization")

            // validate authorization header and extract token
            token, err := extractToken(authorization)
            if err != nil {
                w.Header().Set("WWW-Authenticate", "Bearer")
                w.Write([]byte(`{"detail": "unauthorized"}`))
                return
            }

            // decode payload
            id, err := decodePayload(token)
            if err != nil {
                w.Header().Set("WWW-Authenticate", "Bearer")
                w.Write([]byte(`{"detail": "unauthorized"}`))
                return
            }

            user, err := repo.GetUserByID(r.Context(), id)
            if err != nil {
                w.Write([]byte(`{"detail": "unauthorized"}`))
                return
            }

            ctx := context.WithValue(r.Context(), "user", user)
            next.ServeHTTP(w, r.WithContext(ctx))
        })
    }
}

type PermissionRepository interface {
    GetUserPermissions(ctx context.Context, id int) (entities.Permissions, error)
}

func RequirePermission(permission string, repo PermissionRepository) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            user, ok := r.Context().Value("user").(*entities.User)
            if !ok {
                panic("no user in request context")
            }

            permissions, err := repo.GetUserPermissions(r.Context(), user.ID)
            if err != nil {
                w.WriteHeader(404)
                w.Write([]byte(`{"detail": "no permissions found"}`))
                return
            }

            if !permissions.Can(permission) {
                w.WriteHeader(403)
                w.Write([]byte(`{"detail": "forbidden"}`))
                return
            }

            next.ServeHTTP(w, r)
        })
    }
}

type wrapwriter struct {
    http.ResponseWriter
    written bool
}

func (w *wrapwriter) WriteHeader(code int) {
    w.written = true
    w.ResponseWriter.WriteHeader(code)
}

func (w *wrapwriter) Write(data []byte) (int, error) {
    w.written = true
    return w.ResponseWriter.Write(data)
}

func Recover(logger *slog.Logger) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            ww := &wrapwriter{w, false}

            defer func() {
                if err := recover(); err != nil {
                    logger.Error("server error", "detail", err)
                    if !ww.written {
                        http.Error(w, "internal server error", 500)
                    }
                }
            }()

            next.ServeHTTP(ww, r)
        })
    }
}

func extractToken(_ string) (string, error) {
    // TODO: add implementation
    return "", nil
}

func decodePayload(_ string) (int, error) {
    // TODO: add implementation
    return 0, nil
}

Like I indicated earlier I have left out the logic for authentication, do well to add them yourself. In our snippet we have two functions - Authenticate and RequirePermission. Authenticate verifies who you are and RequirePermission determines what you can do. Both functions return a middleware that carry the logic to perform the processes they describe. Let's stay on the RequirePermission middleware because that's where authorization happens.
RequirePermission tries to get an authenticated user from the request context, if the user doesn't exist, it panics. A panic essentially stops your program, it's the equivalent of throwing an unhandled exception in python but we've added a Recover middleware to avoid crashing our server.

After getting the user, the middleware calls GetUserPermissions from PermissionRepository to get all permissions the user in question has. When this is done, we perform a check to see if the authenticated user has the required permission for access. This is literally what Can does - we discussed it before. If Can returns true, the request moves on to the next middleware down the chain. If it doesn't an error with the status code 403 is sent back as response.

Implementing Posts

Let's implement CRUD for posts. In internal create a posts package and add handler and repository files. In internal/posts/repository.go add the following:

package posts

import (
    "context"
    "errors"

    "github.com/jackc/pgx/v5"

    "demoblog/internal/entities"
)

var (
    ErrNotFound   = errors.New("not found")
    ErrNotAllowed = errors.New("not allowed")
)

type Repository interface {
    CreatePost(ctx context.Context, userID int, param CreatePostParam) (*entities.Post, error)
    UpdatePost(ctx context.Context, postID, userID int, param UpdatePostParam) error
    DeletePost(ctx context.Context, postID, userID int) error
}

type dbtx interface {
    Query(ctx context.Context, query string, args ...any) (pgx.Rows, error)
    QueryRow(ctx context.Context, query string, args ...any) pgx.Row
}

type repository struct {
    db dbtx
}

func NewRepository(db dbtx) *repository {
    return &repository{
        db: db,
    }
}

func (r *repository) CreatePost(ctx context.Context, authorID int, param CreatePostParam) (*entities.Post, error) {
    query := `
  INSERT INTO posts (title, content, slug, author_id) VALUES (@title, @content, @slug, @author_id)
  RETURNING id, title, content, slug, author_id, created_at;
  `

    row := r.db.QueryRow(ctx, query, pgx.NamedArgs{
        "title":     param.Title,
        "content":   param.Content,
        "slug":      slugify(param.Title),
        "author_id": authorID,
    })

    var post entities.Post

    err := row.Scan(
        &post.ID,
        &post.Title,
        &post.Content,
        &post.Slug,
        &post.AuthorID,
        &post.CreatedAt,
    )
    if err != nil {
        return nil, err
    }

    return &post, nil
}

func (r *repository) UpdatePost(ctx context.Context, postID, userID int, param UpdatePostParam) error {
    query := `
  WITH
    post AS (SELECT id, author_id FROM posts WHERE id = @id),
    is_allowed AS (
      SELECT EXISTS (
        SELECT 1 FROM post WHERE
          author_id = @user_id
          OR
          EXISTS (
            SELECT 1 FROM users u
            JOIN user_roles ur ON u.id =  ur.user_id
            JOIN roles r ON ur.role_id = r.id
            WHERE r.role = 'admin' AND u.id = @user_id
        )
      ) AS allowed
    ),
    updated AS (
      UPDATE posts SET
        title = @title,
        content = @content
      WHERE id = @id AND (SELECT allowed FROM is_allowed)
      RETURNING 1
    )

  SELECT
    EXISTS (SELECT 1 FROM post) AS post_exists,
    (SELECT allowed FROM is_allowed) AS is_allowed;`

    row := r.db.QueryRow(ctx, query, pgx.NamedArgs{
        "id":      postID,
        "user_id": userID,
        "title":   param.Title,
        "content": param.Content,
    })

    var ok, isAllowed bool

    if err := row.Scan(&ok, &isAllowed); err != nil {
        return err
    }

    if !ok {
        return ErrNotFound
    }

    if !isAllowed {
        return ErrNotAllowed
    }

    return nil
}

func (r *repository) DeletePost(ctx context.Context, postID, userID int) error {
    query := `
  WITH
    post AS (SELECT id, author_id FROM posts WHERE id = @id),
    is_allowed AS (
      SELECT EXISTS (
        SELECT 1 FROM post WHERE
          author_id = @user_id
          OR
          EXISTS (
            SELECT 1 FROM users u
            JOIN user_roles ur ON u.id = ur.user_id
            JOIN roles r ON ur.role_id = r.id
            WHERE r.role = 'admin' AND u.id = @user_id
          )
      ) AS allowed
    ),
    deleted AS (DELETE FROM posts WHERE id = @id AND (SELECT allowed FROM is_allowed) RETURNING 1)

  SELECT
    EXISTS (SELECT 1 FROM post) AS post_exists,
    (SELECT allowed FROM is_allowed) AS is_allowed;`

    row := r.db.QueryRow(ctx, query, pgx.NamedArgs{
        "id":      postID,
        "user_id": userID,
    })

    var ok, isAllowed bool

    if err := row.Scan(&ok, &isAllowed); err != nil {
        return err
    }

    if !ok {
        return ErrNotFound
    }

    if !isAllowed {
        return ErrNotAllowed
    }

    return nil
}

func slugify(_ string) string {
    //TODO: add implementation
    return ""
}

We've got quite a number of moving pieces here so let's go over them. We have a repository struct that holds 3 methods - CreatePost, UpdatePost, DeletePost all of which perform the actions they describe. The queries for update and delete are a bit of a handful. They shouldn't scare you though, I have just used a CTE - common table expression in both instances to confirm the resource in question exists and the necessary permissions are checked before the main operation is executed. As per our original intention, we want both an admin and the author of a post to be able to update and delete posts - that's exactly what we've done with those queries. Common table expressions are quite handy, if you aren't familiar already, you should learn them.

Let's add post handlers:

package posts

import (
    "encoding/json"
    "io"
    "net/http"
    "strconv"

    "demoblog/internal/entities"
)

type CreatePostParam struct {
    Title   string `json:"title" validate:"required"`
    Content string `json:"content" validate:"required"`
}

type UpdatePostParam struct {
    Title   *string `json:"title" validate:"required"`
    Content *string `json:"content" validate:"required"`
}

type handler struct {
    repo Repository
}

func NewHandler(repo Repository) *handler {
    return &handler{
        repo: repo,
    }
}

func (h *handler) CreatePost(w http.ResponseWriter, r *http.Request) error {
    var param CreatePostParam

    defer r.Body.Close()

    b, err := io.ReadAll(r.Body)
    if err != nil {
        return err
    }

    if err := json.Unmarshal(b, &param); err != nil {
        return err
    }

    // validate params here

    user := r.Context().Value("user").(*entities.User)

    post, err := h.repo.CreatePost(r.Context(), user.ID, param)
    if err != nil {
        return err
    }

    return json.NewEncoder(w).Encode(post)
}

func (h *handler) UpdatePost(w http.ResponseWriter, r *http.Request) error {
    id, err := strconv.Atoi(r.PathValue("id"))
    if err != nil {
        return err
    }

    var param UpdatePostParam

    defer r.Body.Close()
    b, err := io.ReadAll(r.Body)
    if err != nil {
        return err
    }

    if err := json.Unmarshal(b, &param); err != nil {
        return err
    }

    // validate params here

    user := r.Context().Value("user").(*entities.User)

    if err := h.repo.UpdatePost(r.Context(), id, user.ID, param); err != nil {
        return err
    }

    w.WriteHeader(200)
    return nil
}

func (h *handler) DeletePost(w http.ResponseWriter, r *http.Request) error {
    id, err := strconv.Atoi(r.PathValue("id"))
    if err != nil {
        return err
    }

    user := r.Context().Value("user").(*entities.User)

    if err := h.repo.DeletePost(r.Context(), id, user.ID); err != nil {
        return err
    }

    w.WriteHeader(204)
    return nil
}

As we've routinely done, we have a handler struct, that holds methods for creating a post - CreatePost, updating a post - UpdatePost and deleting a post - DeletePost. All they basically do is collect user input, pass them to sections of our code that need them and return the appropriate response.

Adding Routes

We have written most of the logic required for authorization so let's put it all together. We'll need to adjust our entry file. In main.go make the following changes:

// ...

func (app *application) mount() {
    app.handler = func() http.Handler {
        mux := http.NewServeMux()

        routes.MountUser(mux, app.UserStore, app.PermissionStore)
        routes.MountPost(mux, app.PostStore, app.PermissionStore)

        return utils.Combine(
            mux,
            middleware.Recover(app.logger),
            // Add global middlewares here
        )
    }
}

// ...

func main() {
    var cfg config

    flag.IntVar(&cfg.port, "port", 3000, "application port")
    flag.StringVar(&cfg.dsn, "pg-dsn", os.Getenv("POSTGRES_DSN"), "postgres database connection")
    flag.Parse()

    ctx := context.Background()
    ctx, cancel := signal.NotifyContext(ctx, syscall.SIGTERM, syscall.SIGINT)
    defer cancel()

    db, err := pgx.Connect(ctx, cfg.dsn)
    if err != nil {
        log.Fatal(err)
    }

    if err := db.Ping(ctx); err != nil {
        log.Fatal(err)
    }

    defer db.Close(ctx)

    app := &application{
        cfg:             cfg,
        logger:          slog.Default(),
        UserStore:       users.NewRepository(db),
        PostStore:       posts.NewRepository(db),
        PermissionStore: permissions.NewRepository(db),
    }

    if err := app.run(ctx); err != nil {
        log.Fatal(err)
    }
}

We've made a couple of changes to our main.go file. We added some more properties to our application struct - UserStore, PostStore and PermissionStore. They all reference their respective repositories. We fleshed out the mount method with functions from routes - which we will implement shortly. We passed our http multiplexer as an argument to utils.Combine. utils.Combine is just a helper function that calls middlewares in reverse order. Here's what it looks like:

package utils

import "net/http"

func Combine(h http.Handler, mids ...func(http.Handler) http.Handler) http.Handler {
    for i := len(mids) - 1; i >= 0; i-- {
        h = mids[i](h)
    }
    return h
}

In config we added a dsn property for our database connection. In our main function we initialized the database and passed it as an argument to the repositories that need them. Now lets get to work on our routes package. In internal create a routes package and add files for user routes and post routes.

In internal/routes/user.go add the following:

package routes

import (
    "net/http"

    "demoblog/internal/entities"
    "demoblog/internal/middleware"
    "demoblog/internal/permissions"
    "demoblog/internal/users"
    "demoblog/internal/utils"
)

func MountUser(mux *http.ServeMux, store users.Repository, permission permissions.Repository) {
    handler := users.NewHandler(store)

    mux.Handle("POST /api/register", utils.Wrap(handler.CreateUser))

    mux.Handle("GET /api/users", utils.Combine(
        utils.Wrap(handler.ListUsers),
        middleware.RequirePermission(entities.UsersRead, permission),
        // Add route specific middleware here
    ))

    mux.Handle("PATCH /api/users/{id}/role", utils.Combine(
        utils.Wrap(handler.EditUserRole),
        middleware.RequirePermission(entities.UsersUpdate, permission),
        // Add route specific middleware here
    ))
}

In internal/routes/post.go add the following:

package routes

import (
    "net/http"

    "demoblog/internal/entities"
    "demoblog/internal/middleware"
    "demoblog/internal/permissions"
    "demoblog/internal/posts"
    "demoblog/internal/utils"
)

func MountPost(mux *http.ServeMux, store posts.Repository, permission permissions.Repository) {
    handler := posts.NewHandler(store)

    mux.Handle("POST /api/posts", utils.Combine(
        utils.Wrap(handler.CreatePost),
        middleware.RequirePermission(entities.PostsWrite, permission),
        // Add route specific middleware here
    ))

    mux.Handle("PATCH /api/posts/{id}", utils.Combine(
        utils.Wrap(handler.UpdatePost),
        middleware.RequirePermission(entities.PostsUpdate, permission),
        // Add route specific middleware here
    ))

    mux.Handle("DELETE /api/posts/{id}", utils.Combine(
        utils.Wrap(handler.DeletePost),
        middleware.RequirePermission(entities.PostsDelete, permission),
        // Add route specific middleware here
    ))
}

And that brings us to the end of our implementation. Assuming you have followed along till this point and filled out the missing parts of our code, you've successfully implemented RBAC. Congratulations. You can restart your server and test with any http client.

I did however promise to add a cache by the end. Let's do just that.

Adding a Cache

Why do we even need a cache you ask? let's think about the problem caching in this instance solves. When a client hits a protected endpoint, we get a token from the request header, decode the token, make a database call to fetch the user associated with said token then add that user to the request context. If the same endpoint requires permissions, we have to make another database call to fetch permissions for the logged in user. That second database call doesn't need to happen every time, we can cache it to reduce latency.

In internal create a cache package and add the following:

package cache

import (
    "context"
    "fmt"
    "sync"
    "time"
)

type CacheItem struct {
    data string
    exp  time.Time
}

type Cache struct {
    mu   *sync.RWMutex
    data map[string]*CacheItem
}

func New(ctx context.Context) *Cache {
    c := &Cache{
        mu:   &sync.RWMutex{},
        data: make(map[string]*CacheItem),
    }

    c.cleanup(ctx)
    return c
}

func (c *Cache) cleanup(ctx context.Context) {
    go func() {
        ticker := time.NewTicker(3 * time.Minute)
        defer ticker.Stop()

        for {
            select {
            case <-ticker.C:
                c.mu.Lock()
                now := time.Now()
                for key, value := range c.data {
                    if now.After(value.exp) {
                        delete(c.data, key)
                    }
                }
                c.mu.Unlock()
            case <-ctx.Done():
                return
            }
        }
    }()
}

func (c *Cache) Set(_ context.Context, key, value string, ttl time.Duration) error {
    c.mu.Lock()
    defer c.mu.Unlock()
    c.data[key] = &CacheItem{
        data: value,
        exp:  time.Now().Add(ttl),
    }
    return nil
}

func (c *Cache) Get(_ context.Context, key string) (string, error) {
    c.mu.RLock()
    defer c.mu.RUnlock()
    now := time.Now()
    item, ok := c.data[key]
    if !ok || now.After(item.exp) {
        return "", fmt.Errorf("item not found")
    }
    return item.data, nil
}

func (c *Cache) Del(_ context.Context, key string) error {
    c.mu.Lock()
    defer c.mu.Unlock()
    delete(c.data, key)
    return nil
}

func (c *Cache) Flush(_ context.Context) error {
    c.mu.Lock()
    defer c.mu.Unlock()
    for key := range c.data {
        delete(c.data, key)
    }
    return nil
}

We are using a dictionary as cache in this example but you can very easily swap the dictionary out for a redis client. In the code we have a Cache struct that holds a dictionary and a mutex. Go's dictionaries are famously not concurrency safe so we need to add a mutex to manage access. The Cache struct has a couple of methods that basically described the actions they perform. cleanup does a periodic check to remove expired cache items, it's a blocking operation therefore it needs its own goroutine. We call the method in the cache's constructor function - New

Now that we have a cache let's use it. Since we fetch permissions in the middleware package we'll use our cache there.
In middleware/middleware.go make the following changes:

// ...

type cacher interface {
    Set(ctx context.Context, key, value string, ttl time.Duration) error
    Get(ctx context.Context, key string) (string, error)
}

type CachedPermissionRepository struct {
    repo  PermissionRepository
    cache cacher
    ttl   time.Duration
}

func NewCachedPermissionRepository(repo PermissionRepository, cache cacher, ttl time.Duration) *CachedPermissionRepository {
    return &CachedPermissionRepository{
        repo,
        cache,
        ttl,
    }
}

func GetKey(id any) string {
    return fmt.Sprintf("user_[%v]:permissions", id)
}

func (c *CachedPermissionRepository) GetUserPermissions(ctx context.Context, id int) (entities.Permissions, error) {
    key := GetKey(id)

    items, err := c.cache.Get(ctx, key)
    if err == nil {
        return strings.Split(items, ","), nil
    }

    permissions, err := c.repo.GetUserPermissions(ctx, id)
    if err != nil {
        return nil, err
    }

    go func() {
        ctx := context.Background()
        c.cache.Set(ctx, key, strings.Join(permissions, ","), c.ttl)
    }()

    return permissions, nil
}

// rest of the code remains unchanged

func RequirePermission(permission string, repo PermissionRepository) func(http.Handler) http.Handler {
// ...

We just added an adapter. An adapter is a structural design pattern that acts as a wrapper between 2 objects. In this instance we used CachedPermissionRepository to wrap PermissionRepository. They both implement GetUserPermissions and that's precisely why they can be used together or interchangeably. CachedPermissionRepository requires a cache. Its GetUserPermissions method checks the cache for permissions first, if there is a cache hit, it returns the user's permissions. If it's a miss, the method calls the GetUserPermissions on the repository to fetch permissions from the database. When we get them, we spin up a goroutine to save them in the cache and return them to the middleware. Every time there's a cache hit, we save ourselves a trip to the database and that in turn makes our response time faster. Nothing about the middleware itself has to change thanks to our adapter.

We are almost done with caching - there's just one more problem we have to solve - our cache data can become stale. Let's fix that.

To fix this we need a way to tell when a user's role has changed. When roles change, old permissions become stale and our cached data is useless. Postgres has a PUB/SUB mechanism for notifying when changes happen on a table - pg_notify and that's what we'll use. In our migrations file, add the following:

// ...

CREATE OR REPLACE FUNCTION notify_role_change() RETURNS TRIGGER AS $$
DECLARE
    id INT;
    payload TEXT;
BEGIN
    if (TG_OP = 'DELETE') then
        id = OLD.user_id;
    else
        id = NEW.user_id;
    end if;

    payload = json_build_object(
        'action', TG_OP,
        'data', id
    )::text;

    perform pg_notify('role_change', payload);
    RETURN NULL;
END;
$$
LANGUAGE PLPGSQL;

CREATE OR REPLACE TRIGGER notify_role_change_trigger AFTER INSERT OR UPDATE OR DELETE ON user_roles
FOR EACH ROW EXECUTE PROCEDURE notify_role_change();

Here we've written a postgres trigger on user_roles that executes notify_role_change every time an insert, update or delete happens. notify_role_change captures the operation being performed and the id of the user whose role is either being inserted, updated or deleted. TG_OP is a postgres property that can either be INSERT, UPDATE or DELETE. We put the information we've collected in a JSON object with - json_build_object, cast it to text and pass it as an argument to pg_notify.
In practice, every time there's an insert, update or delete on user_roles, postgres publishes a payload that contains the information aforementioned. You subscribe to get this payload by listening on the channel it was published to. The channel is the first argument you pass to pg_notify - in our case it is role_change.
In our code, we can now write a function that constantly listens for changes on user_roles and invalidate our cache every time there is a change to the table.

In internal create an events package and add the following:

package events

import (
    "context"
    "encoding/json"
    "fmt"
    "time"

    "github.com/jackc/pgx/v5"
)

const (
    RoleChange = "role_change"
)

type EventPayload struct {
    Action string `json:"action"`
    Data   any    `json:"data"`
}

func Listen(ctx context.Context, dsn, channel string, onListen func(payload EventPayload), onFail func()) {
    go func() {
        for {
            if err := listen(ctx, dsn, channel, onListen); err != nil {
                if err := ctx.Err(); err != nil {
                    return
                }
                onFail()
            }

            select {
            case <-ctx.Done():
                return
            case <-time.After(3 * time.Second):
            }
        }
    }()
}

func listen(ctx context.Context, dsn, channel string, onListen func(payload EventPayload)) error {
    db, err := pgx.Connect(ctx, dsn)
    if err != nil {
        return err
    }

    defer db.Close(ctx)
    query := fmt.Sprintf("LISTEN %s;", channel)

    if _, err := db.Exec(ctx, query); err != nil {
        return err
    }

    for {
        notif, err := db.WaitForNotification(ctx)
        if err != nil {
            return err
        }

        var payload EventPayload
        if err := json.Unmarshal([]byte(notif.Payload), &payload); err != nil {
            return err
        }

        onListen(payload)
    }
}

Here we've got two functions working in tandem - Listen and listen. listen holds the logic for listening for notifications while Listen handles errors and retries when the database connection is lost. onListen is a callback function that is called only when we have successfully received a notification. When we get one, we know for sure that the user_roles table has changed and our cache data is stale. This is precisely where we need to invalidate the cache. onFail is called when the database connection is lost just before we try to reconnect. It's also reasonable to flush the cache whenever there's a failure like this to avoid data inconsistency. We will implement cache invalidation and flushing in main.go.

In your main.go make the following changes:

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

    "github.com/jackc/pgx/v5"

    // new imports
    "demoblog/internal/cache"
    "demoblog/internal/events"

    "demoblog/internal/middleware"
    "demoblog/internal/permissions"
    "demoblog/internal/posts"
    "demoblog/internal/routes"
    "demoblog/internal/users"
    "demoblog/internal/utils"
)

type config struct {
    port int
    dsn  string
}

type application struct {
    cfg             config
    // added cache
    cache           *cache.Cache
    logger          *slog.Logger
    handler         func() http.Handler
    UserStore       users.Repository
    PostStore       posts.Repository
    PermissionStore permissions.Repository
}

func (app *application) mount() {
    app.handler = func() http.Handler {
        mux := http.NewServeMux()

        // passed cache to routes
        routes.MountUser(mux, app.UserStore, app.PermissionStore, app.cache)
        routes.MountPost(mux, app.PostStore, app.PermissionStore, app.cache)

        return utils.Combine(
            mux,
            middleware.Recover(app.logger),
            // Add global middlewares here
        )
    }
}

func (app *application) run(ctx context.Context) error {
    app.mount()

    serv := &http.Server{
        Addr:    fmt.Sprintf(":%d", app.cfg.port),
        Handler: app.handler(),
    }

    select {
    case err := <-app.serve(serv):
        return err
    case <-ctx.Done():
        return app.shutdown(serv)
    }
}

func (app *application) serve(serv *http.Server) <-chan error {
    ch := make(chan error, 1)
    go func() {
        ch <- serv.ListenAndServe()
    }()
    return ch
}

func (app *application) shutdown(serv *http.Server) error {
    ctx := context.Background()
    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
    defer cancel()
    return serv.Shutdown(ctx)
}

func main() {
    var cfg config

    flag.IntVar(&cfg.port, "port", 3000, "application port")
    flag.StringVar(&cfg.dsn, "pg-dsn", os.Getenv("POSTGRES_DSN"), "postgres database connection")
    flag.Parse()

    ctx := context.Background()
    ctx, cancel := signal.NotifyContext(ctx, syscall.SIGTERM, syscall.SIGINT)
    defer cancel()

    db, err := pgx.Connect(ctx, cfg.dsn)
    if err != nil {
        log.Fatal(err)
    }

    if err := db.Ping(ctx); err != nil {
        log.Fatal(err)
    }

    defer db.Close(ctx)

    // initialized cache
    cache := cache.New(ctx)

    // listen for role_change event
    events.Listen(
        ctx, cfg.dsn,
        events.RoleChange,
        func(payload events.EventPayload) {
            ctx := context.Background()
            switch payload.Action {
            case "INSERT":
            case "UPDATE":
                fallthrough
            case "DELETE":
                cache.Del(ctx, middleware.GetKey(payload.Data))
            }
        },
        func() {
            ctx := context.Background()
            cache.Flush(ctx)
        },
    )

    app := &application{
        cfg:             cfg,
        logger:          slog.Default(),
        // pass cache to application
        cache:           cache,
        UserStore:       users.NewRepository(db),
        PostStore:       posts.NewRepository(db),
        PermissionStore: permissions.NewRepository(db),
    }

    if err := app.run(ctx); err != nil {
        log.Fatal(err)
    }
}

I added comments to specify the changes we made but I'll like to highlight our onListen argument. onListen basically just removes a user permissions from the cache whenever the user's role has changed in the database - usually after an update or a delete. We do nothing on insert because the cache doesn't have that data yet.

Our route functions also accepts the cache as argument now. Let's adjust our routes to use the adapter we added.

In internal/routes/posts.go make the following changes

package routes

import (
    "net/http"
    "time"

    // new import
    "demoblog/internal/cache"
    "demoblog/internal/entities"
    "demoblog/internal/middleware"
    "demoblog/internal/permissions"
    "demoblog/internal/posts"
    "demoblog/internal/utils"
)

// accepts cache as a parameter
func MountPost(mux *http.ServeMux, store posts.Repository, permission permissions.Repository, cache *cache.Cache) {
    handler := posts.NewHandler(store)

    // initialize adapter
    cpermission := middleware.NewCachedPermissionRepository(permission, cache, 15*time.Minute)

    mux.Handle("POST /api/posts", utils.Combine(
        utils.Wrap(handler.CreatePost),
        // use adapter in place of permissions repository
        middleware.RequirePermission(entities.PostsWrite, cpermission),
        // Add route specific middleware here
    ))

    mux.Handle("PATCH /api/posts/{id}", utils.Combine(
        utils.Wrap(handler.UpdatePost),
        // use adapter in place of permissions repository
        middleware.RequirePermission(entities.PostsUpdate, cpermission),
        // Add route specific middleware here
    ))

    mux.Handle("DELETE /api/posts/{id}", utils.Combine(
        utils.Wrap(handler.DeletePost),
        // use adapter in place of permissions repository
        middleware.RequirePermission(entities.PostsDelete, cpermission),
        // Add route specific middleware here
    ))
}

In internal/routes/users.go make the following changes:

package routes

import (
    "net/http"
    "time"

    // new import
    "demoblog/internal/cache"
    "demoblog/internal/entities"
    "demoblog/internal/middleware"
    "demoblog/internal/permissions"
    "demoblog/internal/users"
    "demoblog/internal/utils"
)

// accepts cache as a parameter
func MountUser(mux *http.ServeMux, store users.Repository, permission permissions.Repository, cache *cache.Cache) {
    handler := users.NewHandler(store)

    // initialize adapter
    cpermission := middleware.NewCachedPermissionRepository(permission, cache, 15*time.Minute)

    mux.Handle("POST /api/register", utils.Wrap(handler.CreateUser))

    mux.Handle("GET /api/users", utils.Combine(
        utils.Wrap(handler.ListUsers),
        // use adapter in place of permissions repository
        middleware.RequirePermission(entities.UsersRead, cpermission),
        // Add route specific middleware here
    ))

    mux.Handle("PATCH /api/users/{id}/role", utils.Combine(
        utils.Wrap(handler.EditUserRole),
        // use adapter in place of permissions repository
        middleware.RequirePermission(entities.UsersUpdate, cpermission),
        // Add route specific middleware here
    ))
}

And there we have it people, promise fulfilled. Remember to fill out the parts of the code I left out. If you followed along till this point, get a life man :).

Exploring Rate Limiting in Go

IamKhan — Tue, 16 Dec 2025 16:09:44 +0000

Let's explore rate limiting together in go. If you are here, you probably already know what rate limiting is and why it is important but spare me half a minute to do a brief intro for the guys at the back.

Rate limiting is a technique used to restrict the number of requests a client can make to a server within a specific time window.

Why do I need a rate limiter you ask? to prevent DDoS attacks. What is a DDoS attack you ask? DDoS is acronym for Distributed Denial of Service. When your server is suddenly inundated with an absurb amount of internet traffic, you're are probably experiencing a DDoS attack.

Now that we have gotten definitions out of the way, let's talk about some common rate limiting algorithms. There are quite a number of rate limiting algorithms with varying degrees of complexity, resource usage and trade offs. I'll be exploring 3 of the more common rate limiting strategies:

Fixed window counter
Sliding window counter
Token bucket algorithm

In this expedition, I'll be focusing on the fixed window counter strategy.

Fixed Window Counter

This is the simplest and most common algorithm used for rate limiting. It is essentially acts like a timer for incoming traffic. It is an excellent chioce for low risk APIs where slight traffic spikes aren't a problem. A drawback to this algorithm is the burstiness that can occur immediately the window resets - which in plain english means an attacker can basically make 2 times the request allowed in one window a second before and immediately after the window resets. If your API allows 10 requests per minute, an attacker can wait for the last second of that minute make 10 requests then and make another immediately after the counter resets - that's 20 requests in 2 seconds.

Let's write a go implementation of this strategy

Start a go project and create your entry file. In your entry file create a http server and with an example handler

package main

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

const DEFAULT_PORT = 3000

func hello(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusOK)
    w.Write([]byte(`{"message": "hello"}`))
}

func main() {
    mux := http.DefaultServeMux
    mux.Handle("/", hello)

    serv := &http.Server{
        Addr: fmt.Sprintf(":%d", DEFAULT_PORT),
        Handler: mux,
    }

    if err := serv.ListenAndServe(); err != nil {
        log.Fatal(err)
    }
}

We should now be able to run our server, visit http://localhost:3000 and get a "hello world" response in our client. Right now, we can send an unrestricted number of http requests to the server. Let's add rate limiting to fix that.

In the same directory create a ratelimit package. In your limiter.go file let's write our rate limiting logic

package ratelimit

import (
    "fmt"
    "encoding/json"
    "net"
    "net/http"
    "strings"
    "sync"
    "time"
)

type Counter struct {
    value     int // tracks the number of visits
    windowEnd time.Time // tracks expiration time
}

type RateLimiter struct {
    windowSize time.Duration // window duration
    counters   map[string]*Counter // holds counter information per IP
    mu         sync.Mutex
    maxRequest int // maximum number requests
}

func newRateLimiter(maxRequest int, windowSize time.Duration) *RateLimiter {
    // initialise rate limiter
    limiter := &RateLimiter{
        maxRequest: maxRequest,
        windowSize: windowSize,
        counters:   make(map[string]*Counter),
    }

    // start a goroutine to cleanup expired counters
    go func() {
        t := time.NewTicker(time.Minute)
        defer t.Stop()
        // do cleanup every minute
        for range t.C {
            limiter.cleanup()
        }
    }()

    return limiter
}

func (r *RateLimiter) cleanup() {
    r.mu.Lock()
    defer r.mu.Unlock()
    now := time.Now()

    // remove expired counters
    for key, c := range r.counters {
        if now.After(c.windowEnd) {
            delete(r.counters, key)
        }
    }
}

type LimiterInfo struct {
    Allowed   bool
    Remaining int
    Reset     time.Time
}

func (r *RateLimiter) allow(key string) (bool, LimiterInfo) {
    r.mu.Lock()
    defer r.mu.Unlock()
    now := time.Now()

    // check if counter exists
    c, ok := r.counters[key]

    // if it doesn't create a counter and add to the counters map
    if !ok || now.After(c.windowEnd) {
        c := Counter{
            value:     1,
            windowEnd: now.Add(r.windowSize),
        }

        r.counters[key] = &c

        return true, LimiterInfo{
            Allowed:   true,
            Remaining: r.maxRequest - 1,
            Reset:     c.windowEnd,
        }
    }

    // check if maximum amount of requests exceeded
    if c.value < r.maxRequest {
        // increment value count
        c.value++

        return true, LimiterInfo{
            Allowed:   true,
            Remaining: r.maxRequest - c.value,
            Reset:     c.windowEnd,
        }
    }

    return false, LimiterInfo{
        Allowed:   false,
        Remaining: 0,
        Reset:     c.windowEnd,
    }
}

// helper function to help get client IP
func getRequestIP(r *http.Request) string {
    if ips := r.Header.Get("X-Forwarded-For"); ips != "" {
        parts := strings.Split(ips, ",")
        return parts[0]
    }

    if ip := r.Header.Get("x-Real-IP"); ip != "" {
        return ip
    }

    ip, _, err := net.SplitHostPort(r.RemoteAddr)
    if err != nil {
        return r.RemoteAddr
    }

    return ip
}

// create middleware function
func New(maxRequest int, windowSize time.Duration) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        // create limiter in closure
        limiter := newRateLimiter(maxRequest, windowSize)

        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            // get IP address
            key := getRequestIP(r)

            // check if window is valid
            allowed, info := limiter.allow(key)

            // set rate limiter headers
            w.Header().Set("X-RateLimit-Limit", fmt.Sprint(limiter.maxRequest))
            w.Header().Set("X-RateLimit-Remaining", fmt.Sprint(info.Remaining))
            w.Header().Set("X-RateLimit-Reset", fmt.Sprint(info.Reset.Unix()))

            if !allowed {
                // set retry after header
                w.Header().Set("Retry-After", fmt.Sprintf("%.0f", time.Until(info.Reset).Seconds()))

                // set content type header
                w.Header().Set("Content-Type", "application/json")

                // set status code
                w.WriteHeader(http.StatusTooManyRequests)

                // send json response
                json.NewEncoder(w).Encode(map[string]string{
                    "detail": "rate limit exceeded",
                    "retry_after": info.Reset.Format(time.RFC1123),
                })

                return
            }

            next.ServeHTTP(w, r)
        })
    }
}

Now let's adjust our main.go file to use the rate limiter

import (
    // imports remain the same
    "time"

    ratelimit "path-to-ratelimit-package"
)

func main() {
    mux := http.DefaultServeMux

    // rate limiter allows 2 requests per minute 
    limiter := ratelimit.New(2, time.Minute)
    mux.Handle("/", limiter(http.HandlerFunc(hello)))

    serv := &http.Server{
        Addr: fmt.Sprintf(":%d", DEFAULT_PORT),
        Handler: mux,
    }

    if err := serv.ListenAndServe(); err != nil {
        log.Fatal(err)
    }
}

If you try making a request to the appropriate endpoint more than 2 times in one minute, you'll get a 429 error status code.

Powershell is low-key cool

IamKhan — Thu, 04 Dec 2025 13:51:50 +0000

As far as developer tools go, Microsoft gets a bad rep. There's a long list of reasons tools built by the big M get clowned on but it's hard to deny obvious success stories like VSCode among others - however few.

One tool I think is actually good but not talked about enough is powershell. If you use a windows machine you've
probably come across it - yep, it's that shell that shows up in your VSCode integrated terminal before you adjust
your settings to use bash instead - well, maybe you shouldn't.

This isn't a dump bash and pick up powershell exposition, I use both (you will too) - this is a give powershell
a chance appeal.

What exactly is powershell? Well, it's a command-line shell and it's also a scripting language - just like bash is. While both have a lot of similarities, the fundamental difference between both technologies lie in their approach to handling data. In bash, the output of a command is a text stream; with powershell however, the output of a command is a stream of .NET objects.

What I intend to do with this article is share one of the ways I use powershell in my local development process.

Everyone who has done any work with javascript is familiar with nodemon. It is a dev tool that watches files and
restarts your program when a change is detected. When I started writing golang, I needed golang's nodemon. I didn't find air (go's nodemon alternative) in time so I wrote a simple powershell script I still use till this day.

Here's how I did it:

In your powershell terminal, create a directory.

# create a directory called watcher
mkdir watcher

Fun fact, "mkdir" is a bash command. The underlying cmdlet (as they are called in powershell) for creating directories is New-Item. New-Item is a cmdlet that takes a few arguments. In true powershell fashion the proper way to create a directory from your terminal is:

New-Item -Path watcher -Item-Type directory

But that's too verbose and so the wonderful folks that gave us powershell decided to provide bash-like aliases to quite a number of powershell cmdlet. When you see what looks like a bash command in powershell it really is an alias for a powershell cmdlet.

Now that we have a directory to work with, "cd" into it and create few files:

# go into watcher
cd watcher

# create a go file
ni main.go

# create a powershell script
ni watcher.ps1

Before we continue, you might need to adjust the execution policy option in your terminal. This is important because the wrong option can stop your script from executing.

# check execution policy
Get-ExecutionPolicy

# if response is RemoteSigned you're fine
# if it isn't set execution policy
Set-ExecutionPolicy RemoteSigned

In your go file write some code - that prints something to the terminal. This isn't an article about go, you can replicate the same process for any other language.

package main

import "fmt"

func main() {
    // prints "Hello World to the terminal"
    fmt.Println("Hello World")
}

Before we start writing our script, let's go over what we are trying to build. We want to write a script that continuously watches go files and restarts our program whenever a changed is made to any of the files being watched. We will do this
by tracking the hash of each file. In simple terms, if a file changes, so will its hash; when the hash change, we re-run the program. It's that simple.

# go file path
$path = "main.go"


# write welcome message
Write-Host 'GoWatcher *Press CTRL+C to quit*'

# current directory
$dirname = "."

# recursively get all files in the current directory as well as nested directories
$files = Get-ChildItem $dirname -Filter "*.go" -Recurse

# run go program - initial run
go run $path

# get file hash, sort them and parse the result as string
$signature = $files | Get-FileHash -ErrorAction SilentlyContinue | Sort-Object Path | Out-String

# start a while loop to continuously track file changes
while($true) {
    # get file hash, sort them and parse the result as string again - for comparison (will be different if there's been a change)
    $current_signature = $files | Get-FileHash -ErrorAction SilentlyContinue | Sort-Object Path | Out-String

    # check for a change
    if ($signature -ne $current_signature) {
        Write-Host 'File change detected: Restarting...'

        # re-run go program
        go run $path

        # swap new signature for old one
        $signature = $current_signature
    }

    # sleep for 300 milliseconds
    Start-Sleep -Milliseconds 300
}

Here we have a powershell script that tracks all go files in a directory starts the program and re-runs it when a change is made to any go file.

A small adjustment we can make to the script is - pass the path value via the terminal as a flag. That's quite easy to do - just add the following to the top the file.

[CmdletBinding()]
Param(
    [Parameter(Mandatory)]
    $path
)

# go file path
# $path = "main.go"

In your terminal you can run the script file by typing the script name ("./watcher.ps1") followed by the path argument

./watcher.ps1 -path 'main.go'

We aren't quite done. If the go app performs a blocking/long-running operation, our watcher script will freeze. An example of a blocking operation is a web server.

Now let's adjust out script accordingly.

Just before we begin, I'd like us to take a detour and talk a little bit about jobs in powershell. They are a way to run scripts or commands asynchronously. They are perfect for allowing you perform long running processes in the background of your current session. They are quite easy to start:

# start a background job
Start-Job -Name GoServer -ScriptBlock {
    # perform long running task here
}

# stop a background job
Stop-Job -Name GoServer

# remove a background job
Remove-Job -Name GoServer

# receive response from a background job
Receive-Job -Name GoServer

# get a job
Get-Job -Name GoServer

Now that we've gone over some powershell job specific commands, let's write a script that will fix the issue we have with the first script.

[CmdletBinding()]
Param(
    [Parameter(Mandatory)]
    $path
)

# write welcome message
Write-Host 'GoWatcher *Press CTRL+C to quit*'

# current directory
$dirname = "."

# job name
$jobname = "GoServer"

# binary name
$binary = "GoApp"

# create a function that starts a job
function Start-ServerJob {
    # quietly stop previously running job
    # important because our watcher restarts when a file changes
    Get-Job -Name $jobname -ErrorAction SilentlyContinue | Remove-Job -Force

    # start new job
    # use the argument list parameter to pass values to the job
    $job = Start-Job -Name $jobname -ScriptBlock {
        param($path, $dirname)
        # set location
        Set-Location $dirname

        # build go script to avoid that annoying popup that shows up any time we run a go server
        go run build -o "bin/$binary.exe" $path

        # run binary
        Invoke-Expression "./bin/$binary.exe"
    } -ArgumentList $path, $dirname

    return $job
}

# recursively get all files in the current directory as well as nested directories
$files = Get-ChildItem $dirname -Filter "*.go" -Recurse

# start job - initial run
$job = Start-ServerJob

# get file hash, sort them and parse the result as string
$signature = $files | Get-FileHash -ErrorAction SilentlyContinue | Sort-Object Path | Out-String

# run a while loop in a try-finally block because we want to perform clean-up when the watcher is terminated
try {
    while($true) {
        # get file hash, sort them and parse the result as string again - for comparison (will be different if there's been a change)
        $current_signature = $files | Get-FileHash -ErrorAction SilentlyContinue | Sort-Object Path | Out-String

        # check for a change
        if ($signature -ne $current_signature) {
            Write-Host 'File change detected: Restarting...'

            # re-run the job
            $job = Start-ServerJob

            # swap new signature for old one
            $signature = $current_signature
        }
    }
}
# clean-up - release resources locked up by job
finally {
    # quietly stop previously running job
    # important because our watcher restarts when a file changes
    Get-Job -Name $jobname -ErrorAction SilentlyContinue | Remove-Job -Force

    # stop process if running
    if (Get-Process -Name $binary -ErrorAction SilentlyContinue) {
        Stop-Process -Name $binary -Force
    }
}

Just like that, we have a script that can watch a long running process. We can run a go web server and our script
will watch for changes.

There is a pesky little issue though, since we have the go server running as a background job, we do not get any logs.
We can fix this easily with the Receive-Job cmdlet

# in the while loop, after the signature check, add the following if statement
if ($job -and $job.HasMoreData) {
    # collect job data
    $logs = Receive-Job -Job $job

    # loop over job data and log to the console
    foreach($log in $logs) {
        Write-Host $log
    }
}

Problem fixed. Now let's combine the logic from both scripts into one:

[CmdletBinding()]
param(
  [Parameter(Mandatory)]
  $Path,
  [Parameter()]
  [ValidateSet('Basic', 'Server')]
  $Mode = 'Basic'
)

$Jobname = "GoApp"
$BinaryName = "goapp"
$Dirname = "."

Write-Host 'GoWatcher ' -Foregroundcolor green -NoNewLine
Write-Host '*Press CTRL+C to terminate*' -Foregroundcolor red
Write-Host '**************************************' -Foregroundcolor green

function Run-BasicMode {
  go run $Path

  $files = Get-ChildItem -Path "." -Filter "*.go" -Recurse
  $signature = $files | Get-FileHash -ErrorAction SilentlyContinue | Sort-Object Path | Out-String

  while ($true) {
    $current_signature = $files | Get-FileHash -ErrorAction SilentlyContinue | Sort-Object Path | Out-String

    if ($signature -ne $current_signature) {
      Write-Host 'File change detected: Restarting...' -Foregroundcolor yellow
      go run $Path
      $signature = $current_signature
    }

    Start-Sleep -Milliseconds 100
  }
}


function Start-ServerJob {
  Get-Job -Name $Jobname -ErrorAction SilentlyContinue | Remove-Job -Force

  $job = Start-Job -Name $Jobname -ScriptBlock {
    param($dirname, $path)
    Set-Location $dirname
    go build -o "bin/$BinaryName.exe" $path
    Invoke-Expression "./bin/goapp.exe"
  } -ArgumentList $Dirname, $Path

  return $job
}

function Run-ServerMode {
  $job = Start-ServerJob

  $files = Get-ChildItem . -Filter '*.go' -Recurse
  $signature = $files | Get-FileHash -ErrorAction SilentlyContinue | Sort-Object Path | Out-String

  try {
    while($true) {
      $current_signature = $files | Get-FileHash -ErrorAction SilentlyContinue | Sort-Object Path | Out-String
      if ($signature -ne $current_signature) {
        Write-Host 'File change detected: Restarting...' -Foregroundcolor yellow
        $job = Start-ServerJob
        $signature = $current_signature
      }

      if ($job -and $job.HasMoreData) {
        $logs = Receive-Job -Job $job
        foreach ($log in $logs) {
          Write-Host $log
        }
      }

      Start-Sleep -Milliseconds 300
    }
  }
  finally {
    Get-Job -Name $Jobname -ErrorAction SilentlyContinue | Remove-Job -Force

    if (Get-Process -Name $BinaryName -ErrorAction SilentlyContinue) {
      Stop-Process -Name $BinaryName -Force
    }
  }
}

switch ($Mode) {
  'Basic' { Run-BasicMode }
  'Server' { Run-ServerMode }
}

With the logic for both operations combined, we can now run the script with the appropriate flags depending on your need

# run the script in basic mode
./watcher.ps1 -Path main.go -Mode Basic

#run the script in server mode
./watcher.ps1 -Path main.go -Mode Server

To avoid the need to copy the script into every project we can add an alias to $PROFILE. On a windows machine,
$PROFILE is the path to the current user's powershell profile script. It loads every time powershell is opened.

# Set-Alias **add name** **add path to watcher script**
Set-Alias watcher 'C:/Users/Documents/scripts/watcher.ps1'

Now you can run your go programs with this script from any directory in powershell by running the command:

# for basic mode
watcher -Path main.go -Mode Basic

# for server mode
watcher -Path main.go -Mode Server

Organize your desktop: Build a file organizer in Go.

IamKhan — Wed, 20 Nov 2024 10:30:11 +0000

Is your desktop chaotic? Do you have files of all sorts cluttering your desktop or downloads directory? Let's fix that with a simple script.

As we do at the beginning of any go project, we generate our go.mod file with the "go mod init" directive. To keep things simple, we will write all of our logic in our main.go file.

Let's talk a little about how we will like the script to behave before we write any code. We want to be able to organize our files into directories that indicate the file type or creation date. In short, we want our script to sort video files into a videos directory, music files into a music directory and so on; or sort all files created on a particular date into the same directory.

Now let's code:

Create a main.go file and write the following:

package main

type fileAnalyzer interface {
    analyzeAndSort() error
}

func analyze(fa fileAnalyzer) error {
    return fa.analyzeAndSort()
}

Because we want our program to sort files by different criteria, we create a fileAnalyzer interface that defines a method: analyzeAndSort.
Then we write a function: analyze - that takes any struct that implements the fileAnalyzer interface as an argument and executes its analyzeAndSort method.

In some cases like we will see in this program, there may be certain files you don't want moved. For example, while testing the script, we don't want the program to move our go files or executable/binary into another directory. To prevent this from happening, we have to create a blacklist that includes all the files we will like to remain untouched.

In our main.go file, write the following:

var blacklist = []string{
    "go",
    "mod",
    "exe",
    "ps1",
}

Here, I added the file extension for files I will like to remain unsorted. ".go" and ".mod" are extensions for go files. Because I use a windows machine, my binary will have ".exe" as its extension. I also included ".ps1" because I like to work with powershell scripts in development - as you will see.

Next, we write some helper functions.

func getFileExtension(name string) string {
    return strings.TrimPrefix(filepath.Ext(name), ".")
}

func listFiles(dirname string) ([]string, error) {
    var files []string

    list, err := os.ReadDir(dirname)
    if err != nil {
        return nil, err
    }

    for _, file := range list {
        if !file.IsDir() {
            files = append(files, file.Name())
        }
    }

    return files, nil
}

func listDirs(dirname string) ([]string, error) {
    var dirs []string

    list, err := os.ReadDir(dirname)
    if err != nil {
        return nil, err
    }

    for _, file := range list {
        if file.IsDir() {
            dirs = append(dirs, file.Name())
        }
    }

    return dirs, nil
}

func mkdir(dirname string) error {
    err := os.Mkdir(dirname, 0644)

    if err != nil && os.IsExist(err) {
        return nil
    }

    var e *os.PathError

    if err != nil && errors.As(err, &e) {
        return nil
    }

    return err
}

func moveFile(name string, dst string) error {
    return os.Rename(name, filepath.Join(dst, name))
}

func getCurrentDate(t time.Time) string {
    return t.Format("2006-01-02")
}

func filter[T any](ts []T, fn func(T) bool) []T {
    filtered := make([]T, 0)

    for i := range ts {
        if fn(ts[i]) {
            filtered = append(filtered, ts[i])
        }
    }

    return filtered
}

Most of these are self-explanatory but I'll like to talk about the "mkdir" function. The "mkdir" function creates a directory with the name passed to it as argument - but the function does not return an error if the directory already exists or if there is an "os.PathError".

Now let's create a struct that implements the fileAnalyzer interface:

type fileTypeAnalyzer struct {
    wd     string
    mapper map[string][]string
}

func newFileTypeAnalyzer(wd string) *fileTypeAnalyzer {
    return &fileTypeAnalyzer{
        wd: wd,
        mapper: map[string][]string{
            "video":  {"mp4", "mkv", "3gp", "wmv", "flv", "avi", "mpeg", "webm"},
            "music":  {"mp3", "aac", "wav", "flac"},
            "images": {"jpg", "jpeg", "png", "gif", "svg", "tiff"},
            "docs":   {"docx", "csv", "txt", "xlsx"},
            "books":  {"pdf", "epub"},
        },
    }
}

func (f fileTypeAnalyzer) analyzeAndSort() error {
    files, err := listFiles(f.wd)
    if err != nil {
        return fmt.Errorf("could not list files: %w", err)
    }

    if err := f.createFileTypeDirs(files...); err != nil {
        return err
    }

    return f.moveFileToTypeDir(files...)
}

func (f fileTypeAnalyzer) moveFileToTypeDir(files ...string) error {
    dirs, err := listDirs(f.wd)
    if err != nil {
        return fmt.Errorf("could not list directories: %w", err)
    }

    for _, dir := range dirs {
        for _, file := range files {
            if slices.Contains(f.mapper[dir], strings.ToLower(getFileExtension(file))) {
                if err := moveFile(file, dir); err != nil {
                    return err
                }
            }
        }
    }

    files, err = listFiles(f.wd)
    if err != nil {
        return err
    }

    if len(files) == 0 {
        return nil
    }

    files = filter(files, func(f string) bool {
        return !slices.Contains(blacklist, getFileExtension(f))
    })

    for i := range files {
        if err := f.moveToMisc(files[i]); err != nil {
            return err
        }
    }

    return nil
}

func (f fileTypeAnalyzer) moveToMisc(file string) error {
    if err := mkdir("misc"); err != nil {
        return err
    }

    return moveFile(file, "misc")
}

func (f fileTypeAnalyzer) createFileTypeDirs(files ...string) error {
    for ftype, fvalues := range f.mapper {
        for _, file := range files {
            if slices.Contains(fvalues, getFileExtension(file)) {
                if err := mkdir(ftype); err != nil {
                    return fmt.Errorf("could not create folder: %w", err)
                }
            }
        }
    }

    return nil
}

The fileTypeAnalyzer struct has two properties: wd which holds the name of the current working directory and a mapper. The mapper's keys will be the type of file detected while its values is a list of file extensions associated with the key. We then create a constructor function and provide the file types as well as their associative file extensions to the mapper. Feel free to add more file types and extensions to the list. The anaylyzeAndSort method calls a couple of helper functions and methods that maps file extension to a file type, creates the file type directory and moves the file into said directory. I also added a "misc" folder to hold files that were not captured by the mapper - excluding the blacklisted files of course.

We also want to be able to organize files by creation date. Let's create another struct that implements the fileAnalyzer interface but organizes files by date.

type fileDateAnalyzer struct {
    wd string
}

func newFileDateAnalyzer(wd string) *fileDateAnalyzer {
    return &fileDateAnalyzer{
        wd: wd,
    }
}

func (f fileDateAnalyzer) analyzeAndSort() error {
    files, err := listFiles(f.wd)
    if err != nil {
        return fmt.Errorf("could not list files: %w", err)
    }

    if err := f.createFileDateDirs(files...); err != nil {
        return err
    }

    return f.moveFileToDateDir(files...)
}

func (f fileDateAnalyzer) createFileDateDirs(files ...string) error {
    for _, file := range files {
        info, err := os.Stat(file)
        if err != nil {
            return err
        }

        if !slices.Contains(blacklist, getFileExtension(file)) {
            if err := mkdir(getCurrentDate(info.ModTime())); err != nil {
                return err
            }
        }
    }

    return nil
}

func (f fileDateAnalyzer) moveFileToDateDir(files ...string) error {
    dirs, err := listDirs(f.wd)
    if err != nil {
        return fmt.Errorf("could not list directories: %w", err)
    }

    files = filter(files, func(f string) bool {
        return !slices.Contains(blacklist, getFileExtension(f))
    })

    for _, dir := range dirs {
        for _, file := range files {
            info, err := os.Stat(file)
            if err != nil {
                continue
            }

            if dir == getCurrentDate(info.ModTime()) {
                if err := moveFile(file, dir); err != nil {
                    continue
                }
            }
        }
    }

    return nil
}

A lot of the logic is the same as that from the fileTypeAnalyzer. The main difference is we are not providing a mapper - instead we get the creation date from the file info and create directories accordingly.

Now let's put everything together in our main function:

func main() {
    logger := slog.Default()
    slog.SetDefault(logger)

    var analyzer fileAnalyzer

    wd, err := os.Getwd()
    if err != nil {
        log.Fatal(err)
    }

    var mode string

    flag.StringVar(&mode, "mode", "", "Provide sort mode (type|date)")
    flag.Parse()

    switch mode {
    case "date":
        analyzer = newFileDateAnalyzer(wd)
    case "type":
        analyzer = newFileTypeAnalyzer(wd)
    default:
        fmt.Println("Provide sort mode flag: --mode=(type|date)")
        return
    }

    if err := analyze(analyzer); err != nil {
        log.Fatal(err)
    }
}

We configure a logger; get the current working directory to pass as an argument to our fileAnalyzer implementation; create a mode variable to hold values passed in as flags to the application and a switch statement to control how we want to sort. Finally we call the analyze function and pass our fileAnalyzer implementation as argument.

That's all. Let's build our binary and test. I called mine sorter. You can call yours whatever you want to call it with "go build -o [name]"

Here is a folder littered with files of different types:

Let's organize by file type:

Let's organize by file creation date:

As a bonus, if you use a windows machine and you use powershell - here's a script to help make testing your program seemless.

Create a task.ps1 file and type the following:

[CmdletBinding()]
Param(
  [Parameter(Mandatory)][string]$Action
)

function Get-Dirs {
  [CmdletBinding()]
  Param(
    [Parameter(Mandatory)][string]$Path
  )
  return Get-ChildItem -Path $Path | Where-Object { $_.GetType() -eq [System.IO.DirectoryInfo] }
}

switch($Action) {
  'build' {
    Write-Host -ForegroundColor green 'building binary...'
    go build -o sorter.exe
  }
  'remove' {
    $folders = Get-Dirs -Path '.'

    foreach($folder in $folders) {
      if ((Get-ChildItem $folder).Count -eq 0) {
        Remove-Item $folder
      } else {
        Write-Host -ForegroundColor yellow 'folder not empty'
      }
    }
  }
  'unsort' {
    Write-Host -ForegroundColor green 'unsorting...'
    Get-ChildItem (Get-Dirs -Path '.') | ForEach-Object { $_ | Move-Item -Destination '.' }
  }
  Default {
    Write-Host -ForegroundColor red 'invalid action'
  }
}

To build your binary with the script:

To unorganize files with the script:

To delete directories with script:

Let's build a password generator we can actually use

IamKhan — Wed, 13 Nov 2024 01:37:04 +0000

For our next beginner project, we will build a password generator that doesn't only generate passwords but encrypts and saves them - so that it is actually functional.

We will be splitting our code into different files so we don't end up with a large "main.go" file.

First, we initialize a go project and create a "profile.go" file that will contain the logic for encrypting and decrypting passwords.

package main

import (
    "crypto/aes"
    "crypto/cipher"
    "crypto/rand"
    "encoding/hex"
    "errors"
    "io"
)

// must be 32 characters 
var key = "askdjasjdbreonfsdfibsdhfgsdfhboo"

var ErrMalformedEncryption = errors.New("malformed encryption")

// password in small letters so it is not stored
type profile struct {
    Enc, Platform, password string
}

func (p *profile) encrypt() error {
    block, err := aes.NewCipher([]byte(key))
    if err != nil {
        return err
    }

    gcm, err := cipher.NewGCM(block)
    if err != nil {
        return err
    }

    nonce := make([]byte, gcm.NonceSize())

    if _, err := io.ReadFull(rand.Reader, nonce); err != nil {
        return err
    }

    enc := gcm.Seal(nonce, nonce, []byte(p.password), nil)
    p.Enc = hex.EncodeToString(enc)

    return nil
}

func (p *profile) decrypt() error {
    block, err := aes.NewCipher([]byte(key))
    if err != nil {
        return err
    }

    gcm, err := cipher.NewGCM(block)
    if err != nil {
        return err
    }

    nsize := gcm.NonceSize()

    if len(p.Enc) < nsize {
        return ErrMalformedEncryption
    }

    enc, err := hex.DecodeString(p.Enc)
    if err != nil {
        return err
    }

    password, err := gcm.Open(nil, enc[:nsize], enc[nsize:], nil)
    if err != nil {
        return err
    }

    p.password = string(password)

    return nil
}

Here we create a profile struct that has 3 fields - Enc, Platform and password. Enc will hold the encrypted password, the service we are generating the password for will be stored in Platform and password will hold the actual generated password. The profile struct has 2 methods "encrypt" and "decrypt". We use AES - a symmetric key encryption algorithm to encrypt and decrypt our password.

Next we create a "store.go" file that contains the logic for storing and retrieving passwords.

package main

import (
    "encoding/gob"
    "errors"
    "os"
    "sync"
)

const filename = "profile.bin"

var (
    ErrInvalidArgs = errors.New("invalid args")
    ErrNotFound    = errors.New("not found")
)

type store struct {
    sync.RWMutex
    data map[string]*profile
}

func newStore() (*store, error) {
    s := &store{
        data: make(map[string]*profile),
    }

    if err := s.load(); err != nil {
        return nil, err
    }

    return s, nil
}

func (s *store) load() error {
    flags := os.O_CREATE | os.O_RDONLY
    f, err := os.OpenFile(filename, flags, 0644)
    if err != nil {
        return err
    }
    defer f.Close()

    info, err := f.Stat()
    if err != nil {
        return err
    }

    if info.Size() == 0 {
        return nil
    }

    return gob.NewDecoder(f).Decode(&s.data)
}

func (s *store) save() error {
    f, err := os.OpenFile(filename, os.O_WRONLY, 0644)
    if err != nil {
        return err
    }
    defer f.Close()

    return gob.NewEncoder(f).Encode(s.data)
}

func (s *store) find(platform string) (string, error) {
    s.RLock()
    defer s.RUnlock()

    p, ok := s.data[platform]
    if !ok {
        return "", ErrNotFound
    }

    if err := p.decrypt(); err != nil {
        return "", err
    }

    return p.password, nil
}

func (s *store) add(platform, password string) error {
    if platform == "" {
        return ErrInvalidArgs
    }

    p := &profile{
        Platform: platform,
        password: password,
    }

    if err := p.encrypt(); err != nil {
        return err
    }

    s.Lock()
    defer s.Unlock()

    s.data[platform] = p

    return s.save()
}

We chose gob files for storage because they are not exactly human readable. If the file ever gets exposed, your passwords are safe because they will be encrypted and really difficult to read. The store struct contains methods for loading, finding and saving to the gob file. We save the passwords in a dictionary. We also use a mutex to make the dictionary concurrent safe. An important thing to note is that we will not be storing the plain generated password - we will store its encrypted value instead.

Now let's write a couple of functions that will actually generate the passwords. Create a "password.go" file and type the following

package main

import (
    "math"
    "math/rand"
    "slices"
    "strings"
)

const (
    half      = .5
    onethird  = .3
    onefourth = .25
)

var (
    randlowers  = randFromSeed(lowers())
    randuppers  = randFromSeed(uppers())
    randdigits  = randFromSeed(digits())
    randsymbols = randFromSeed(symbols())
)

var basicPassword = randlowers

func mediumPassword(n int) string {
    frac := math.Round(float64(n) * half)
    pwd := basicPassword(n)
    return pwd[:n-int(frac)] + randuppers(int(frac))
}

func hardPassword(n int) string {
    pwd := mediumPassword(n)
    frac := math.Round(float64(n) * onethird)
    return pwd[:n-int(frac)] + randdigits(int(frac))
}

func xhardPassword(n int) string {
    pwd := hardPassword(n)
    frac := math.Round(float64(n) * onefourth)
    return pwd[:n-int(frac)] + randsymbols(int(frac))
}

func randFromSeed(seed string) func(int) string {
    return func(n int) string {
        var b strings.Builder
        for range n {
            b.WriteByte(seed[rand.Intn(len(seed))])
        }
        return b.String()
    }
}

func lowers() string {
    var b strings.Builder
    for i := 'a'; i < 'a'+26; i++ {
        b.WriteRune(i)
    }
    return b.String()
}

func uppers() string {
    var b strings.Builder
    for i := 'A'; i < 'A'+26; i++ {
        b.WriteRune(i)
    }
    return b.String()
}

func symbols() string {
    var b strings.Builder
    for i := '!'; i < '!'+14; i++ {
        b.WriteRune(i)
    }
    for i := ':'; i < ':'+6; i++ {
        b.WriteRune(i)
    }
    for i := '['; i < '['+5; i++ {
        b.WriteRune(i)
    }
    for i := '{'; i < '{'+3; i++ {
        b.WriteRune(i)
    }
    return b.String()
}

func digits() string {
    var b strings.Builder
    for i := '0'; i < '0'+9; i++ {
        b.WriteRune(i)
    }
    return b.String()
}

func shuffle[T any](ts []T) []T {
    cloned := slices.Clone(ts)
    rand.Shuffle(len(cloned), func(i, j int) {
        cloned[i], cloned[j] = cloned[j], cloned[i]
    })
    return cloned
}

func shuffleStr(s string) string {
    return strings.Join(shuffle(strings.Split(s, "")), "")
}

Here we've written functions that generates passwords at different levels of difficulty. The basicPassword function generates random small letter strings. The mediumPassword function takes a fraction of the characters from basicPassword function and adds random capital letters to it. The hardPassword function does the same for mediumPassword but adds digits to it. The xhardPassword does the same and adds symbols. The shuffle function does exactly what you'd expect on slices while shuffleStr shuffles strings.

Now let's put everything together. Create a "main.go" file and type the following

package main

import (
    "errors"
    "flag"
    "fmt"
    "log"
    "regexp"
    "strconv"
    "strings"
)

var usage = `
Usage 
-----
--get platform=[string] - Gets saved password for a platform
--set platform=[string] len=[int] level=(basic|medium|hard|xhard) - Creates and saves a password
`

var ErrUsage = errors.New(usage)

var pattern = regexp.MustCompile(`\S+=\S+`)

type level int

const (
    _ level = iota
    level_basic
    level_medium
    level_hard
    level_xhard
)

var level_key = map[string]level{
    "basic":  level_basic,
    "medium": level_medium,
    "hard":   level_hard,
    "xhard":  level_xhard,
}

type commands struct {
    get, set bool
}

func createCommands() (c commands) {
    flag.BoolVar(&c.get, "get", false, "get password for platform")
    flag.BoolVar(&c.set, "set", false, "set password for platform")
    flag.Parse()
    return
}

func (c commands) exec(store *store) (string, error) {
    switch {
    case c.get:
        return c.getPassword(store)
    case c.set:
        return c.setPassword(store)
    default:
        return "", ErrUsage
    }
}

func (c commands) getPassword(store *store) (string, error) {
    params, err := c.parse()
    if err != nil {
        return "", err
    }

    return store.find(params["platform"])
}

func (c commands) setPassword(store *store) (string, error) {
    params, err := c.parse()
    if err != nil {
        return "", err
    }

    var password string

    n, err := strconv.Atoi(params["len"])
    if err != nil {
        return "", err
    }

    if n < 8 {
        return "", fmt.Errorf("password len cannot be less than 8")
    }

    switch level_key[params["level"]] {
    case level_basic:
        password = basicPassword(n)
    case level_medium:
        password = mediumPassword(n)
    case level_hard:
        password = hardPassword(n)
    case level_xhard:
        password = xhardPassword(n)
    default:
        return "", ErrUsage
    }

    password = shuffleStr(password)

    if err := store.add(params["platform"], password); err != nil {
        return "", err
    }

    return password, nil
}

func (c commands) parse() (map[string]string, error) {
    args := flag.Args()

    if len(args) == 0 {
        return nil, ErrUsage
    }

    params := make(map[string]string)

    for i := range args {
        if !pattern.MatchString(args[i]) {
            return nil, ErrUsage
        }

        parts := strings.Split(args[i], "=")
        params[parts[0]] = parts[1]
    }

    return params, nil
}

func main() {
    store, err := newStore()
    if err != nil {
        log.Fatalf("could not initialize store: %v", err)
    }

    c := createCommands()

    password, err := c.exec(store)
    if err != nil {
        log.Fatalf("could not execute flag commands: %v", err)
    }

    fmt.Printf("password: %s\n", password)
}

We used flags to specify how we expect the application to behave. "--get" to get a password and "--set" to generate and save a password. To set a password, the user provides arguments with the flags to instruct the application on the type of password to generate and save. To get a password, the user also provides arguments to specify the password to retrieve.

You can now run "go build" to build a binary and test the application.

Writing a Typing Speed Test CLI Application in Golang

IamKhan — Fri, 18 Oct 2024 01:09:27 +0000

Had to think long and hard about that title 🙄... now that we've gotten that out of the way, let's write some darn code :)

Pumps brake 🚗 screechhhhh.... Let's do a bit of introduction into what we will be attempting to build today. Incase the title wasn't obvious, we will be building a CLI application that calculates your typing speed in golang - although you can literally build the same application, following the same techniques in any programming language of your choice.

Now, let's code 😎

package main

import (
    "bufio"
    "fmt"
    "log"
    "math/rand"
    "os"
    "strings"
    "time"
)

var sentences = []string{
    "There are 60 minutes in an hour, 24 hours in a day and 7 days in a week",
    "Nelson Mandela is one of the most renowned freedom fighters Africa has ever produced",
    "Nigeria is the most populous black nation in the world",
    "Peter Jackson's Lord of the rings is the greatest film of all time",
}

In our main.go file, we import the packages we will need to write our logic. We also create a slice of sentences. Feel free to add a bunch more.

// A generic helper function that randomly selects an item from a slice
func Choice[T any](ts []T) T {
    return ts[rand.Intn(len(ts))]
}

// Prompts and collects user input from the terminal
func Input(prompt string) (string, error) {
    fmt.Print(prompt)
    r := bufio.NewReader(os.Stdin)

    line, err := r.ReadString('\n')
    if err != nil {
        return "", err
    }

    return strings.Trim(line, "\n\r\t"), nil
}

// Compares two strings and keeps track of the characters  
// that match and those that don't
func CompareChars(target, source string) (int, int) {
    var valid, invalid int

    // typed some of the words
        // resize target to length of source
    if len(target) > len(source) {
        diff := len(target) - len(source)
        invalid += diff
        target = target[:len(source)]
    }

    // typed more words than required
        // resize source to length of target
    if len(target) < len(source) {
        invalid++
        source = source[:len(target)]
    }

    for i := 0; i < len(target); i++ {
        if target[i] == source[i] {
            valid++
        }
        if target[i] != source[i] {
            invalid++
        }
    }

    return valid, invalid
}

// Calculates the degree of correctness
func precision(pos, fal int) int {
    return pos / (pos + fal) * 100
}

// Self explanatory - don't stress me 😑
func timeElapsed(start, end time.Time) float64 {
    return end.Sub(start).Seconds()
}

// Refer to the last comment
func accuracy(correct, total int) int {
    return (correct / total) * 100
}

// 😕
func Speed(chars int, secs float64) float64 {
    return (float64(chars) / secs) * 12
}

We then go on to create a couple of function that will come in handy when we write our application logic.

func main() {
    fmt.Println("Welcome to Go-Speed")
    fmt.Println("-------------------")

    for {
        fmt.Printf("\nWould you like to continue? (y/N)\n\n")
        choice, err := Input(">> ")
        if err != nil {
            log.Fatalf("could not read value: %v", err)
        }

        if choice == "y" {
            fmt.Println("Starting Game...")
            timer := time.NewTimer(time.Second)
            fmt.Print("\nBEGIN TYPING NOW!!!\n\n")
            _ = <-timer.C

            sentence := Choice(sentences)
            fmt.Printf("%s\n", sentence)

            start := time.Now()
            response, err := Input(">> ")
            if err != nil {
                log.Fatalf("could not read value: %v", err)
            }

            elasped := timeElapsed(start, time.Now())
            valid, invalid := CompareChars(sentence, response)
            fmt.Print("\nResult!\n")
            fmt.Println("-------")
            fmt.Printf("Correct Characters: %d\nIncorrect Characters: %d\n", valid, invalid)
            fmt.Printf("Accuracy: %d%%\n", accuracy(valid, len(sentence)))
            fmt.Printf("Precision: %d%%\n", precision(valid, invalid))
            fmt.Printf("Speed: %.1fwpm\n", Speed(len(sentence), elasped))
            fmt.Printf("Time Elasped: %.2fsec\n", elasped)
        }

        if choice == "N" {
            fmt.Println("Quiting Game...")
            break
        }

        if choice != "N" && choice != "y" {
            fmt.Println("Invalid Option")
        }
    }
}

In our main function, we write a welcome message to the terminal and create an infinite loop to run our program. We then print a confirmation message to stdout - terminal - with an option to quit the program. If you choose to continue, a sentence is selected from the slice of sentences previously written and displayed in the terminal just after the start time is recorded. We collect the user input and calculate the time, speed, precision and accuracy then display the results back to the terminal. The infinite loop resets and the application runs again until you opt out of the program.

Voila!!! We just wrote our first program in golang.