DEV Community: Samuel Umoh

Implement Authorization with Role-Based Access Control (RBAC) in Golang

Samuel Umoh — Tue, 30 Jun 2026 16:20:58 +0000

This is part 2 of our authentication and authorization series. In the previous part, we implemented an authentication system from scratch in Golang with Gin and PostgreSQL. Now in this part, we will go further and see how we can implement authorization in our system.

Prerequisites

The requirements to follow along are:

A working laptop or PC with Golang installed.
Some familiarity with Golang and SQL.
Having read the first part of this series (link here).

What is Authorization?

Authorization answers the second half of our dilemma. When we know who you are, surely, we should know what you're allowed to do in our system?

Authorization determines what an authenticated identity (user, application, or service) can do and which resources it can access within a system. It ensures that every authenticated identity operates within defined boundaries. Without it, a user who logs in successfully could access all sensitive data and perform any action.

What Does Authorization Do in Our System?

Authorization connects three main components:

Users (authenticated entities)
Permissions (actions they can perform)
Resources (the things we're protecting)

Common Authorization Models

There are mainly three ways to implement authorization in a system:

Role-Based Access Control (RBAC) RBAC is the foundational authorization model. It simplifies permission management by assigning permissions to roles (e.g., Admin, Driver, User) and then assigning those roles to users.

How it works: The system checks the user's assigned role(s) and aggregates their permissions to determine if the requested action is allowed.
Attribute-Based Access Control (ABAC) ABAC uses dynamic policies that evaluate attributes of the user, the resource, and the environment to make an access decision.

How it works: Access is determined by policy expressions that evaluate in real time (e.g., user.department == resource.department, or checking if the current time falls within business hours).
Relationship-Based Access Control (ReBAC) and Fine-Grained Authorization (FGA) ReBAC bases authorization on the relationships and ownership between a user and a specific resource.

How it works: The system checks for explicit relationships (e.g., "owner of," "shared with," "member of group") to grant or deny access. Current implementations use graph-based relationship modeling to navigate complex permission chains.

In this guide, we will be focusing on implementing RBAC. It's the most common and straightforward to implement, making it a solid starting point.

Database Migrations for RBAC

Now, let's implement RBAC into our Golang authentication system.

First, we need to add some database migrations. In these migrations, we will create:

A roles table to define the available roles.
A permissions table to define the available permissions.
A role_permissions table to establish the many-to-many relationship between roles and permissions.
A user_roles table to establish the many-to-many relationship between users and roles.

So let's create a new database migration:

goose create create_authorization_tables sql

Paste this into the generated migration file:

-- migrations/..._create_authorization_tables.sql

-- +goose Up
-- role
CREATE TABLE roles (
  id SMALLSERIAL PRIMARY KEY,
  name VARCHAR(50) UNIQUE NOT NULL
);
INSERT INTO roles (name)
VALUES ('super-admin'),
  ('admin'),
  ('user'),
  ('guest');
--permissions
CREATE TABLE permissions (
  id SMALLSERIAL PRIMARY KEY,
  name VARCHAR(50) UNIQUE NOT NULL
);
INSERT INTO permissions (name)
VALUES ('create_task'),
  ('read_task'),
  ('update_task'),
  ('delete_task');
-- role permissions
CREATE TABLE role_permissions (
  role_id SMALLINT NOT NULL,
  permission_id SMALLINT NOT NULL,
  PRIMARY KEY (role_id, permission_id),
  FOREIGN KEY (role_id) REFERENCES roles(id) ON DELETE CASCADE,
  FOREIGN KEY (permission_id) REFERENCES permissions(id) ON DELETE CASCADE
);
INSERT INTO role_permissions (role_id, permission_id)
SELECT r.id,
  p.id
FROM (
    VALUES ('super-admin', 'create_task'),
      ('super-admin', 'read_task'),
      ('super-admin', 'update_task'),
      ('super-admin', 'delete_task'),
      ('admin', 'read_task'),
      ('admin', 'update_task'),
      ('admin', 'delete_task'),
      ('user', 'read_task'),
      ('user', 'update_task'),
      ('guest', 'read_task')
  ) AS mappings(role_name, permission_name)
  JOIN roles r ON r.name = mappings.role_name
  JOIN permissions p ON p.name = mappings.permission_name;
-- user roles
CREATE TABLE user_roles (
  user_id UUID NOT NULL,
  role_id SMALLINT NOT NULL,
  PRIMARY KEY (user_id, role_id),
  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
  FOREIGN KEY (role_id) REFERENCES roles(id) ON DELETE CASCADE
);
INSERT INTO user_roles (user_id, role_id)
SELECT u.id,
 r.id
FROM users u
 CROSS JOIN roles r
WHERE r.name = 'user'
 AND NOT EXISTS (
  SELECT 1
  FROM user_roles ur
  WHERE ur.user_id = u.id
   AND ur.role_id = r.id
 );
CREATE INDEX idx_user_roles_user_id_role_id ON user_roles (user_id, role_id);
-- +goose Down
DROP TABLE IF EXISTS roles;
DROP TABLE IF EXISTS permissions;
DROP TABLE IF EXISTS role_permissions;
DROP TABLE IF EXISTS user_roles;
DROP INDEX IF EXISTS idx_user_roles_user_id_role_id;

We also added an insert statement to set a default "user" role to any existing user who doesn't have a role (I mean, they shouldn't before this migration, right?). We then create an index for faster queries.

Now apply the migration:

goose up

RBAC Queries

Next, let's write all our queries and let sqlc run its magic:

-- queries/authorization.sql

-- name: GetRoles :many
SELECT *
FROM roles;
-- name: GetPermissions :many
SELECT *
FROM permissions;
-- name: GetEntityRoles :many
SELECT r.name
FROM user_roles ur
 JOIN roles r ON r.id = ur.role_id
WHERE ur.user_id = $1;
-- name: GetRolePermissions :many
SELECT p.name
FROM role_permissions rp
 JOIN permissions p ON p.id = rp.permission_id
WHERE rp.role_id = $1;
-- name: GetRolePermissionsByRoleName :many
SELECT p.name
FROM roles r
 JOIN role_permissions rp ON rp.role_id = r.id
 JOIN permissions p ON p.id = rp.permission_id
WHERE r.name = $1;
-- name: GetEntityRolesPermissions :many
SELECT DISTINCT p.name
FROM user_roles ur
 JOIN role_permissions rp ON rp.role_id = ur.role_id
 JOIN permissions p ON p.id = rp.permission_id
WHERE ur.user_id = $1;
-- name: AssignRoleToEntity :exec
INSERT INTO user_roles (user_id, role_id)
SELECT $1,
 id
FROM roles
WHERE name = $2;
-- name: RevokeRoleFromEntity :exec
DELETE FROM user_roles
WHERE user_id = $1
 AND role_id = (
  SELECT id
  FROM roles
  WHERE name = $2
 );
-- name: RemoveAllEntityRoles :exec
DELETE FROM user_roles
WHERE user_id = $1;

Then generate the Go code with:

sqlc generate

Great, we have covered most of what we need.

Adding Roles to JWT Claims

Next, we need to update our GenerateAccessToken function to accept roles so they can be added to the JWT claims. This way, we don't have to make a call to our database every time a user hits our RBAC middleware, as that would be very detrimental to performance.

A Note on Alternative Approaches

Another way we can do this is to store the user roles and permissions in Redis.

That way, we will get them from Redis and proceed accordingly. This is actually the better approach because we can invalidate permissions and it will update in real time.

Whereas with our JWT approach, if we invalidate an entity's permissions, those permissions still live until the JWT access token expires, in our case 10-15 minutes.

Now you understand the tradeoff, but for simplicity of this guide, we will pass the roles to the JWT claims and then access them in our RBAC middleware. Everything else is the same, just the choice of where to store it.

Updating GenerateAccessToken

Let's update our GenerateAccessToken function to accept and add roles to the claims:

// pkg/util/auth.go

func GenerateAccessToken(user sqlc.User, roles []string, jwtSecret []byte, accessTokenTTL time.Duration) (string, error) {
    expirationTime := time.Now().UTC().Add(accessTokenTTL)

    claims := jwt.MapClaims{
        "sub":   user.ID.String(),
        "email": user.Email,
        "roles": roles,
        "exp":   expirationTime.Unix(),
        "iat":   time.Now().UTC().Unix(),
    }

    token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)

    tokenString, err := token.SignedString(jwtSecret)
    if err != nil {
        return "", err
    }

    return tokenString, nil
}

Updating the Authentication Handlers

Updating the SignUp Handler

We need to update our signup handler so that when any entity signs up, we assign them a default role. Just before we send the "user created successfully" response, let's add:

// internal/ports/http/handlers/user/user.go

    err = h.queries.AssignRoleToEntity(c, sqlc.AssignRoleToEntityParams{
        UserID: user.ID,
        Name:   "user",
    })

    if err != nil {
        c.JSON(http.StatusInternalServerError, gin.H{
            "message": err.Error(),
        })
        return
    }

Updating the SignIn Handler

Next, we'll have to update our signin handler to get the entity roles so we can pass them to the GenerateAccessToken function we just modified:

// internal/ports/http/handlers/user/user.go

    roles, err := h.queries.GetEntityRoles(c, user.ID)
    if err != nil {
        c.JSON(http.StatusInternalServerError, "error")
        return
    }

    token, err := util.GenerateAccessToken(*user, roles, []byte(h.environmentVariables.Authentication.JWT_SECRET), 30*time.Minute)
    if err != nil {
        c.JSON(http.StatusInternalServerError, gin.H{
            "message": "failed to generate access token",
        })
        return
    }

Updating the RefreshAccessToken Handler

We must also do the same for the RefreshAccessToken handler, as it uses the GenerateAccessToken function as well:

// internal/ports/http/handlers/user/user.go

    roles, err := h.queries.GetEntityRoles(c, user.ID)
    if err != nil {
        c.JSON(http.StatusInternalServerError, "error")
        return
    }

    accessToken, err := util.GenerateAccessToken(*user, roles, []byte(h.environmentVariables.Authentication.JWT_SECRET), 30*time.Minute)
    if err != nil {
        c.JSON(http.StatusInternalServerError, gin.H{
            "message": "failed to generate access token",
        })
        return
    }

Updating the Auth Middleware

Now that our JWT tokens contain role claims, we need to update our AuthMiddleware to extract and set the roles from the token. We also need a new RoleMiddleware that will check if a user has the required roles before granting access to a route.

Updated AuthMiddleware

// internal/ports/http/middleware/auth.go
package middleware

import (
    "net/http"
    "strings"

    "github.com/gin-gonic/gin"
    "github.com/google/uuid"
    "github.com/umohsamuel/authentication-authorization/pkg/env"
    "github.com/umohsamuel/authentication-authorization/pkg/util"
)

func AuthMiddleware(environmentVariables env.EnvironmentVariables) gin.HandlerFunc {
    return func(c *gin.Context) {
        authHeader := c.GetHeader("Authorization")
        if authHeader == "" {
            c.JSON(http.StatusUnauthorized, gin.H{
                "error": "Authorization header required",
            })
            c.Abort()
            return
        }

        parts := strings.Split(authHeader, " ")
        if len(parts) != 2 || parts[0] != "Bearer" {
            c.JSON(http.StatusUnauthorized, gin.H{
                "error": "Invalid authorization format",
            })
            c.Abort()
            return
        }

        tokenString := parts[1]

        claims, err := util.ValidateToken(tokenString, []byte(environmentVariables.Authentication.JWT_SECRET))
        if err != nil {
            c.JSON(http.StatusUnauthorized, gin.H{
                "error": "Invalid or expired token",
            })
            c.Abort()
            return
        }

        userIDStr, ok := claims["sub"].(string)
        if !ok {
            c.JSON(http.StatusUnauthorized, gin.H{
                "error": "Invalid token",
            })
            c.Abort()
            return
        }

        userID, err := uuid.Parse(userIDStr)
        if err != nil {
            c.JSON(http.StatusUnauthorized, gin.H{
                "error": "Invalid token",
            })
            c.Abort()
            return
        }

        rawRoles, ok := claims["roles"].([]interface{})
        if !ok {
            c.JSON(http.StatusUnauthorized, gin.H{
                "error": "Invalid token",
            })
            c.Abort()
            return
        }

        roles := make([]string, len(rawRoles))
        for i, r := range rawRoles {
            roles[i] = r.(string)
        }

        c.Set("userID", userID)
        c.Set("roles", roles)

        c.Next()
    }
}

So now, we also extract roles from the JWT claims (since we added them in our updated GenerateAccessToken) and we set them as well in the Gin context, easy.

RoleMiddleware

Since AuthMiddleware runs first and sets the user's roles in the Gin context, our RoleMiddleware can simply read them and check if the user has the required roles. Now, let's create it:

// internal/ports/http/middleware/auth.go

func RoleMiddleware(requiredRoles []string) gin.HandlerFunc {
    return func(c *gin.Context) {
        rolesValue, exists := c.Get("roles")

        if !exists {
            c.AbortWithStatus(http.StatusUnauthorized)

            return
        }

        roles := rolesValue.([]string)

        hasRole := false

        for _, r := range roles {
            for _, rr := range requiredRoles {
                if r == rr {
                    hasRole = true
                }
            }
        }

        if !hasRole {
            c.JSON(http.StatusForbidden, gin.H{
                "error": "Forbidden",
            })
            c.Abort()
            return
        }

        c.Next()

    }
}

This middleware:

Retrieves the user's roles from the Gin context (remember we set them in the AuthMiddleware).
Loops through the user's roles and checks if any match the required roles for the route.
If the user has at least one of the required roles, the request proceeds. Otherwise, we return a 403 Forbidden response.

Updating the API Routes

Finally, let's update our API routes to reflect our authorization updates:

// cmd/api/api.go

package api

import (
    "net/http"
    "time"

    "github.com/gin-contrib/cors"
    "github.com/gin-gonic/gin"
    "github.com/umohsamuel/authentication-authorization/internal/adapters/database/sqlc"
    "github.com/umohsamuel/authentication-authorization/internal/ports/http/handlers/user"
    "github.com/umohsamuel/authentication-authorization/internal/ports/http/middleware"
    "github.com/umohsamuel/authentication-authorization/pkg/env"
)

type Server struct {
    Engine  *gin.Engine
    Env     *env.EnvironmentVariables
    Queries *sqlc.Queries
}

func API(environmentVariables *env.EnvironmentVariables, queries *sqlc.Queries) *Server {

    s := &Server{
        Engine:  gin.Default(),
        Env:     environmentVariables,
        Queries: queries,
    }

    config := cors.DefaultConfig()
    config.AllowAllOrigins = true
    config.AllowMethods = []string{"POST", "GET", "PUT", "OPTIONS"}
    config.AllowHeaders = []string{"Origin", "Content-Type", "Authorization", "Accept", "User-Agent", "Cache-Control", "Pragma"}
    config.ExposeHeaders = []string{"Content-Length"}
    config.AllowCredentials = true
    config.MaxAge = 12 * time.Hour

    s.Engine.Use(cors.New(config))

    s.Engine.Static("/downloads", "tmp")

    auth := s.Engine.Group("/auth")
    s.Auth(auth)

    v1 := s.Engine.Group("/api/v1")
    {

        protected := v1.Group("")
        protected.Use(middleware.AuthMiddleware(*s.Env))
        {
            s.Health(protected)
            s.OnlyMinLevelAdmin(protected)
        }

    }

    s.Engine.Run()

    return s
}

func (s *Server) Health(rg *gin.RouterGroup) {
    rg.GET("/health", func(ctx *gin.Context) {
        ctx.JSON(http.StatusOK, gin.H{
            "message": "Server Up!",
        })
    })
}

func (s *Server) OnlyMinLevelAdmin(rg *gin.RouterGroup) {
    g := rg.Group("/admin")

    requiredRoles := []string{"super-admin", "admin"}

    g.Use(middleware.RoleMiddleware(requiredRoles))

    g.GET("/test", func(c *gin.Context) {
        c.JSON(200, gin.H{
            "success": "you have successfully implemented RBAC",
        })
    })

}

func (s *Server) Auth(rg *gin.RouterGroup) {
    userHandler := user.NewUserHandler(*s.Env, *s.Queries)

    rg.POST("/signup", userHandler.SignUp)
    rg.POST("/signin", userHandler.SignIn)
    rg.POST("/refresh", userHandler.RefreshAccessToken)

    // admin in case of revoking access token
    rg.POST("/revoke-refresh", userHandler.RevokeRefreshAccessToken)
}

I updated the route structure a little, so it's a bit different from Part 1:

Public routes (/auth/*) handle signup, signin, and token management.
Protected routes (/api/v1/*) use the AuthMiddleware, so you must be authenticated to access them.
Admin routes (/api/v1/admin/*) add an extra layer with RoleMiddleware, so only users with the super-admin or admin role can access them.

Run the Application

Let's do some testing. You can run the application in your terminal with:

go run cmd/main.go

Testing with cURL

If we go to an admin-only route now as a regular user:

export ACCESS_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

curl -X GET http://localhost:8080/api/v1/admin/test \
  -H "Authorization: Bearer $ACCESS_TOKEN"

You should get the response 403:

{
  "error": "Forbidden"
}

You can update your user role from your database using a query tool, or update your signup AssignRoleToEntity to create an admin entity. Then try the route again, and you should get the response:

{
  "success": "you have successfully implemented RBAC"
}

Conclusion

Congratulations, if you have made it this far, you have successfully implemented RBAC authorization. This system we built includes:

Database schema for roles, permissions, and their relationships.
Many-to-many mappings between roles and permissions, and between users and roles.
Default role assignment on user signup.
Role-based middleware to protect routes based on required roles.
A structured API with separated public routes and protected routes.

As usual, you can checkout the source code on Github here: umohsamuel/authentication-and-authorization, play around with it and lmk what you think.

Build a Secure Authentication System in Golang with Gin, JWT, and Postgres

Samuel Umoh — Tue, 30 Jun 2026 16:19:22 +0000

Securing user data is a very important part of building any application. At the core of this security are two foundational concepts: authentication and authorization.

While these terms are often used interchangeably, they represent fundamentally different functions.

What are Authentication and Authorization?

Simply put, authentication is the process of verifying who a user is, while authorization is the process of verifying what they have access to.

Comparing these processes to a real-world example, when you go to write an external examination (say JAMB), a student presents their exam slip and ID card (authentication). Then once inside, they can only sit for the subjects they registered for and not any random exam they choose (authorization).

This simple process is the foundation for web applications; it ensures that the users are who they claim to be and also ensures they can only access what they are allowed to access.

While both are equally important, this article will focus specifically on the first step: how to build a secure authentication system in Golang using JSON Web Tokens and PostgreSQL.

Prerequisites

What would you need to follow along?

Golang installed on your laptop or computer.
Basic familiarity with SQL and Go.

Understanding JSON Web Tokens (JWT)

A JSON Web Token (JWT) is a compact, self-contained way to transmit information between two parties as a JSON object securely. It's designed to ensure data integrity and authenticity without the need for server-side session management. It is secure because the token's data is digitally signed using a shared secret (HMAC) or public/private key pair (RSA).

JWTs are essential in an authentication system because their statelessness eliminates the need for repeated database queries, thereby reducing server load and improving response times.

JWT Structure

A JWT consists of three parts encoded in Base64URL format and separated by dots:

Header.Payload.Signature

For example:

eyJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6InVtb2hzZy5hbHRAZ2LTMzMzlhZDIzNzNjZSJ9.RVQk03jen6HzfHnjXkTiD612gMDrNtFsExWKElWElDg

The header identifies the algorithm used for signing.
The payload contains claims about the user like ID, roles, and expiration time.
The signature verifies the token hasn't been tampered with.

The Role of JWT in Our System

When a user interacts with our system:

When the user successfully authenticates, our Go service:
1. Validates the user credentials against PostgreSQL data.
2. Creates a JWT with the appropriate claims and expiration.
3. Signs the token with a secret key.
The client:
1. Stores the JWT (mostly in localStorage or Cookie).
2. Includes the token in the Authorization header for subsequent requests.
Our middleware:
1. Extracts the JWT from the request header.
2. Validates the signature using our secret key.
3. Checks that the token hasn't expired.
4. Extracts the user identity from the claims.
5. Adds the user ID to the request context.
Since the token contains all the necessary user information, our server can authenticate requests without maintaining session state or making additional database queries.

The security of the JWT system depends on keeping the signing key secret and using short-lived access tokens. If a token is compromised, it's only valid for a limited time, reducing the risk of unauthorized access.

Project Setup and Database Migrations

Let's initialize a new Go application and install the necessary dependencies:

mkdir authentication-authorization
cd authentication-authorization
go mod init github.com/you/authentication-authorization

Now let's install the essential packages:

go get github.com/gin-gonic/gin # HTTP web framework and router
go get github.com/gin-contrib/cors # Cross-Origin Resource Sharing (CORS) middleware
go get github.com/jackc/pgx/v5 # PostgreSQL driver
go get github.com/jackc/pgx/v5/pgconn # PostgreSQL connection
go get github.com/jackc/pgx/v5/pgxpool # Connection pooling
go get github.com/golang-jwt/jwt/v5 # JWT library
go get golang.org/x/crypto/bcrypt # Password hashing
go get github.com/google/uuid # UUID generation
go get github.com/joho/godotenv # Load environment variables

Next, let's install Goose for our database migrations:

go install github.com/pressly/goose/v3/cmd/goose@latest

Next, let's make a migrations folder:

mkdir migrations

Now, let's create our very first migration for this project.

Create a .env file and configure it with your PostgreSQL database credentials (replace GOOSE_DBSTRING with your actual database connection url):

export GOOSE_DRIVER=postgres
export GOOSE_DBSTRING=postgres://admin:admin@localhost:5432/admin_db
export GOOSE_MIGRATION_DIR=./migrations

Open your terminal and run:

goose create create_user_and_refresh_token_table sql

Paste this into the generated migration file:

-- migrations/..._create_user_and_refresh_token_table.sql

-- +goose Up
CREATE TABLE users (
 id uuid PRIMARY KEY DEFAULT uuidv7(),
 email VARCHAR(255) UNIQUE NOT NULL,
 password_hash TEXT NOT NULL,
 created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
);
-- refresh token table
CREATE TABLE refresh_tokens (
 id uuid PRIMARY KEY DEFAULT uuidv7(),
 user_id uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE,
 token VARCHAR(255) UNIQUE NOT NULL,
 expires_at TIMESTAMPTZ NOT NULL,
 created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
 revoked BOOLEAN NOT NULL DEFAULT FALSE
);
-- index for fast lookups
CREATE INDEX idx_refresh_tokens_token ON refresh_tokens(token);
-- +goose Down
DROP TABLE IF EXISTS users;
DROP TABLE IF EXISTS refresh_tokens;
DROP INDEX IF EXISTS idx_refresh_tokens_token;

Now we can apply the migration in our terminal:

goose up

And if you check your PostgreSQL database, the appropriate tables and fields have been created.

Loading Environment Variables

Our application requires configuration such as the Port, database URL and JWT secret. Let's create an env package to handle loading these variables using godotenv:

// pkg/env/env.go

package env

import (
    "log"
    "os"
    "strconv"
   "regexp"

    "github.com/joho/godotenv"
    "github.com/umohsamuel/authentication-authorization/pkg/util"
)

type AuthenticationEV struct {
    JWT_SECRET string
}

type DatabaseEV struct {
    PG_PORT      int
    DATABASE_URL string
}

type EnvironmentVariables struct {
    Port                  string
    ProductionEnvironment bool
    ClientDomain          string
    ProjectName           string
    Authentication        AuthenticationEV
    Database              DatabaseEV
}

func loadEnv() {
    rootPath := GetRootPath()
    err := godotenv.Load(rootPath + `/.env`)

    if err != nil {
        log.Println("Warning: .env file not found, using environment variables")
    }
}

func LoadEnvironmentVariables() *EnvironmentVariables {
    loadEnv()

    return &EnvironmentVariables{
        Port:                  getEnv("PORT", ":5000"),
        ProductionEnvironment: getEnvAsBool("PRODUCTION_ENVIRONMENT", false),
        ClientDomain:          getEnv("CLIENT_DOMAIN", "localhost"),
        ProjectName:           getEnv("PROJECT_NAME", "eba"),
        Authentication: AuthenticationEV{
            JWT_SECRET: getEnvOrError("JWT_SECRET"),
        },
        Database: DatabaseEV{
            PG_PORT:      getEnvAsInt("PG_PORT", 5433),
            DATABASE_URL: getEnvOrError("DATABASE_URL"),
        },
    }
}

func getEnvOrError(key string) string {
    value, exists := os.LookupEnv(key)
    if exists {
        return value
    }
    panic("Environment variable " + key + " not set")
}

func getEnv(key string, fallback string) string {
    value, exists := os.LookupEnv(key)
    if exists {
        return value
    }
    return fallback
}

func getEnvAsInt(key string, fallback int) int {
    value, exist := os.LookupEnv(key)
    if exist {
        valueInt, err := strconv.Atoi(value)
        if err != nil {
            log.Panicf("Environment variable \"%v\" not set properly", key)
        }
        return valueInt
    }
    return fallback
}

func getEnvAsBool(key string, fallback bool) bool {
    value, exist := os.LookupEnv(key)
    if exist {
        valueBool, err := strconv.ParseBool(value)
        if err != nil {
            log.Panicf("Environment variable \"%v\" not set properly", key)
        }
        return valueBool
    }
    return fallback
}

func GetRootPath() string {
    projectDirName := os.Getenv("PROJECT_DIR_NAME")
    projectName := regexp.MustCompile(`^(.*` + projectDirName + `)`)
    currentWorkDirectory, _ := os.Getwd()
    return string(projectName.Find([]byte(currentWorkDirectory)))
}

Make sure to add the relevant environment variables to your .env file:

JWT_SECRET=your-super-secret-jwt-key
DATABASE_URL=postgres://admin:admin@localhost:5432/admin_db

Database Connection Setup

Let's start with a connection to our PostgreSQL Database:

// internal/adapters/database/connection.go

package database

import (
    "context"
    "database/sql"
    "log"
    "os"
    "time"

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


func NewPool() *sql.DB {
    pool, err := pgxpool.New(context.Background(), os.Getenv("DATABASE_URL"))
    if err != nil {
        log.Fatalf("unable to create pg pool: %v", err)
    }

    db := stdlib.OpenDBFromPool(pool)

    db.SetMaxIdleConns(5)
    db.SetMaxOpenConns(25)
    db.SetConnMaxIdleTime(1 * time.Second)
    db.SetConnMaxLifetime(30 * time.Second)

    if err := db.PingContext(context.Background()); err != nil {
        log.Fatalf("unable to reach database: %v", err)
    }

    log.Println("database created & is reachable")

    return db
}

This simple function connects to our PostgreSQL database, creates a connection pool, and pings the database to verify the connection.

Password Hashing

Now we will create functions that will hash passwords safely during registration and verify them during login:

// pkg/util/password.go

func HashPassword(password string) (string, error) {
    bytes, err := bcrypt.GenerateFromPassword([]byte(password), 14)
    return string(bytes), err
}

func CheckPasswordHash(password, hash string) bool {
    err := bcrypt.CompareHashAndPassword([]byte(hash), []byte(password))
    return err == nil
}

We use Bcrypt for password hashing because:

It is slow by design, making it impractical for brute-force attacks.
It is adaptive because it has an adjustable cost factor. This makes computing the hash deliberately computationally expensive, so we can increase security as hardware gets faster.
It automatically salts passwords. This guarantees that even if two users have the exact same password, their stored hashes will look completely different.

When a user signs up, we'll hash their password before storing it. When they log in, we'll compare their provided password against the stored hash.

Database Models and Queries

For our database interactions, we will use sqlc, a powerful tool that generates fully type-safe Go code directly from SQL queries.

Normally, you would configure sqlc and run its CLI to generate these files for you. However, to keep this tutorial focused strictly on the authentication logic, we'll just create the necessary files manually.

First, let's add the foundational db.go file that sqlc uses to define the Queries struct and the database execution interface:

// internal/adapters/database/sqlc/db.go

package sqlc

import (
    "context"
    "database/sql"
)

type DBTX interface {
    ExecContext(context.Context, string, ...interface{}) (sql.Result, error)
    PrepareContext(context.Context, string) (*sql.Stmt, error)
    QueryContext(context.Context, string, ...interface{}) (*sql.Rows, error)
    QueryRowContext(context.Context, string, ...interface{}) *sql.Row
}

func New(db DBTX) *Queries {
    return &Queries{db: db}
}

type Queries struct {
    db DBTX
}

func (q *Queries) WithTx(tx *sql.Tx) *Queries {
    return &Queries{
        db: tx,
    }
}

Now let's create a user model and adapter to interact with:

// internal/adapters/database/sqlc/user.go

package sqlc

import (
    "context"

    "github.com/google/uuid"
)

type User struct {
    ID           uuid.UUID    `json:"id"`
    Email        string       `json:"email"`
    PasswordHash string       `json:"password_hash"`
    CreatedAt    sql.NullTime `json:"created_at"`
}


const addUser = `-- name: AddUser :one
INSERT INTO users (email, password_hash)
VALUES ($1, $2)
RETURNING id, email, password_hash, created_at
`

type AddUserParams struct {
    Email        string `json:"email"`
    PasswordHash string `json:"password_hash"`
}

func (q *Queries) AddUser(ctx context.Context, arg AddUserParams) (*User, error) {
    row := q.db.QueryRowContext(ctx, addUser, arg.Email, arg.PasswordHash)
    var i User
    err := row.Scan(
        &i.ID,
        &i.Email,
        &i.PasswordHash,
        &i.CreatedAt,
    )
    return &i, err
}

const getUser = `-- name: GetUser :one
SELECT id, email, password_hash, created_at
FROM users
WHERE email = $1
`

func (q *Queries) GetUser(ctx context.Context, email string) (*User, error) {
    row := q.db.QueryRowContext(ctx, getUser, email)
    var i User
    err := row.Scan(
        &i.ID,
        &i.Email,
        &i.PasswordHash,
        &i.CreatedAt,
    )
    return &i, err
}

const getUserByID = `-- name: GetUserByID :one
SELECT id, email, password_hash, created_at
FROM users
WHERE id = $1
`

func (q *Queries) GetUserByID(ctx context.Context, id uuid.UUID) (*User, error) {
    row := q.db.QueryRowContext(ctx, getUserByID, id)
    var i User
    err := row.Scan(
        &i.ID,
        &i.Email,
        &i.PasswordHash,
        &i.CreatedAt,
    )
    return &i, err
}

const getUsers = `-- name: GetUsers :many
SELECT id, email, password_hash, created_at
FROM users
`

func (q *Queries) GetUsers(ctx context.Context) ([]*User, error) {
    rows, err := q.db.QueryContext(ctx, getUsers)
    if err != nil {
        return nil, err
    }
    defer rows.Close()
    var items []*User
    for rows.Next() {
        var i User
        if err := rows.Scan(
            &i.ID,
            &i.Email,
            &i.PasswordHash,
            &i.CreatedAt,
        ); err != nil {
            return nil, err
        }
        items = append(items, &i)
    }
    if err := rows.Close(); err != nil {
        return nil, err
    }
    if err := rows.Err(); err != nil {
        return nil, err
    }
    return items, nil
}

This adapter provides methods to interact with a user/users. We'll need them for our authentication logic. The User struct represents the structure of the user data stored in the database.

JWT Generation and Validation

// pkg/util/auth.go

func GenerateAccessToken(user sqlc.User, jwtSecret []byte, accessTokenTTL time.Duration) (string, error) {
    expirationTime := time.Now().UTC().Add(accessTokenTTL)

    claims := jwt.MapClaims{
        "sub":   user.ID.String(),
        "email": user.Email,
        "exp":   expirationTime.Unix(),
        "iat":   time.Now().UTC().Unix(),
    }

    token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)

    tokenString, err := token.SignedString(jwtSecret)
    if err != nil {
        return "", err
    }

    return tokenString, nil
}

func ValidateToken(tokenString string, jwtSecret []byte) (jwt.MapClaims, error) {
    token, err := jwt.Parse(tokenString, func(t *jwt.Token) (interface{}, error) {
        if _, ok := t.Method.(*jwt.SigningMethodHMAC); !ok {
            return nil, errors.New("invalid token")
        }
        return jwtSecret, nil
    })

    if err != nil {
        if errors.Is(err, jwt.ErrTokenExpired) {
            return nil, errors.New("token expired")
        }
        return nil, errors.New("invalid token")
    }

    if claims, ok := token.Claims.(jwt.MapClaims); ok && token.Valid {
        return claims, nil
    }
    return nil, errors.New("invalid token")
}

Short-lived access tokens are more secure, but they require users to log in frequently.

To improve user experience while maintaining security, we can implement a refresh token system. This essentially creates a two-tier authentication system, where a long-lived refresh token is used to obtain short-lived access tokens.

The refresh token can be revoked if needed, allowing for better control over user sessions.

Refresh Token Management

// internal/adapters/database/sqlc/refresh_token.go

package sqlc

import (
    "context"
    "time"

    "github.com/google/uuid"
)

type RefreshToken struct {
    ID        uuid.UUID `json:"id"`
    UserID    uuid.UUID `json:"user_id"`
    Token     string    `json:"token"`
    ExpiresAt time.Time `json:"expires_at"`
    CreatedAt time.Time `json:"created_at"`
    Revoked   bool      `json:"revoked"`
}

const createRefreshToken = `-- name: CreateRefreshToken :one
INSERT INTO refresh_tokens (user_id, token, expires_at)
VALUES ($1, $2, $3)
RETURNING id, user_id, token, expires_at, created_at, revoked
`

type CreateRefreshTokenParams struct {
    UserID    uuid.UUID `json:"user_id"`
    Token     string    `json:"token"`
    ExpiresAt time.Time `json:"expires_at"`
}

func (q *Queries) CreateRefreshToken(ctx context.Context, arg CreateRefreshTokenParams) (*RefreshToken, error) {
    row := q.db.QueryRowContext(ctx, createRefreshToken, arg.UserID, arg.Token, arg.ExpiresAt)
    var i RefreshToken
    err := row.Scan(
        &i.ID,
        &i.UserID,
        &i.Token,
        &i.ExpiresAt,
        &i.CreatedAt,
        &i.Revoked,
    )
    return &i, err
}

const getRefreshToken = `-- name: GetRefreshToken :one
SELECT id, user_id, token, expires_at, created_at, revoked
FROM refresh_tokens
WHERE token = $1
`

func (q *Queries) GetRefreshToken(ctx context.Context, token string) (*RefreshToken, error) {
    row := q.db.QueryRowContext(ctx, getRefreshToken, token)
    var i RefreshToken
    err := row.Scan(
        &i.ID,
        &i.UserID,
        &i.Token,
        &i.ExpiresAt,
        &i.CreatedAt,
        &i.Revoked,
    )
    return &i, err
}

const revokeRefreshToken = `-- name: RevokeRefreshToken :exec
UPDATE refresh_tokens
SET revoked = true
WHERE token = $1
`

func (q *Queries) RevokeRefreshToken(ctx context.Context, token string) error {
    _, err := q.db.ExecContext(ctx, revokeRefreshToken, token)
    return err
}

The main benefits of refresh tokens are that they:

Allow access tokens to be short-lived (e.g., 15 minutes), which reduces the risk if they're leaked.
Enable longer sessions without requiring frequent logins.
Can be revoked server-side if needed, such as on logout or if a security breach is detected.

User Authentication Handlers

Now let's create our user authentication handler:

// internal/ports/http/handlers/user/user.go

package user

import (
    "net/http"
    "time"

    "github.com/gin-gonic/gin"
    "github.com/google/uuid"
    "github.com/umohsamuel/authentication-authorization/internal/adapters/database/sqlc"
    "github.com/umohsamuel/authentication-authorization/pkg/env"
    "github.com/umohsamuel/authentication-authorization/pkg/util"
)

type Handler struct {
    environmentVariables env.EnvironmentVariables
    queries              sqlc.Queries
}

func NewUserHandler(environmentVariables env.EnvironmentVariables, queries sqlc.Queries) *Handler {
    return &Handler{
        environmentVariables: environmentVariables,
        queries:              queries,
    }
}

type SignUpRequest struct {
    Email    string `json:"email"`
    Password string `json:"password"`
}

func (h *Handler) SignUp(c *gin.Context) {
    var signUpReq SignUpRequest

    if err := c.ShouldBindJSON(&signUpReq); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{
            "message": "invalid request params",
        })
        return
    }

    password_hash, err := util.HashPassword(signUpReq.Password)
    if err != nil {
        c.JSON(http.StatusInternalServerError, gin.H{
            "message": "",
        })
        return
    }

    user, err := h.queries.AddUser(c, sqlc.AddUserParams{
        Email:        signUpReq.Email,
        PasswordHash: password_hash,
    })
    if err != nil {
        c.JSON(http.StatusInternalServerError, gin.H{
            "message": err.Error(),
        })
        return
    }

    c.JSON(http.StatusCreated, gin.H{
        "message": "user created successfully",
        "data":    user,
    })
}

type SignInRequest struct {
    Email    string `json:"email"`
    Password string `json:"password"`
}

func (h *Handler) SignIn(c *gin.Context) {
    var signInReq SignInRequest

    if err := c.ShouldBindJSON(&signInReq); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{
            "message": "invalid request params",
        })
        return
    }

    user, err := h.queries.GetUser(c, signInReq.Email)
    if err != nil {
        c.JSON(http.StatusBadRequest, gin.H{
            "message": "user not found",
        })
        return
    }

    if password_match := util.CheckPasswordHash(signInReq.Password, user.PasswordHash); password_match != true {
        c.JSON(http.StatusBadRequest, gin.H{
            "message": "invalid details",
        })
        return
    }

    token, err := util.GenerateAccessToken(*user, []byte(h.environmentVariables.Authentication.JWT_SECRET), 30*time.Minute)
    if err != nil {
        c.JSON(http.StatusInternalServerError, gin.H{
            "message": "failed to generate access token",
        })
        return
    }

    refreshToken, err := h.queries.CreateRefreshToken(c, sqlc.CreateRefreshTokenParams{
        UserID:    user.ID,
        Token:     uuid.New().String(),
        ExpiresAt: time.Now().UTC().Add(7 * 24 * time.Hour),
    })
    if err != nil {
        c.JSON(http.StatusInternalServerError, gin.H{
            "message": "failed to generate refresh token",
        })
        return
    }

    c.JSON(http.StatusOK, gin.H{
        "message": "login successful",
        "data":    user,
        "jwt": gin.H{
            "token":         token,
            "refresh_token": refreshToken.Token,
        },
    })
}

type RefreshAccessTokenRequest struct {
    RefreshToken string `json:"refresh_token"`
}

func (h *Handler) RefreshAccessToken(c *gin.Context) {
    var refreshAccessReq RefreshAccessTokenRequest

    if err := c.ShouldBind(&refreshAccessReq); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{
            "message": "invalid request params",
        })
        return
    }

    rt, err := h.queries.GetRefreshToken(c, refreshAccessReq.RefreshToken)
    if err != nil {
        c.JSON(http.StatusUnauthorized, gin.H{
            "message": "invalid refresh token",
        })
        return
    }

    if rt.Revoked {
        c.JSON(http.StatusUnauthorized, gin.H{
            "message": "invalid refresh token",
        })
        return
    }

    if time.Now().UTC().After(rt.ExpiresAt) {
        c.JSON(http.StatusUnauthorized, gin.H{
            "message": "expired refresh token",
        })
        return
    }

    user, err := h.queries.GetUserByID(c, rt.UserID)
    if err != nil {
        c.JSON(http.StatusUnauthorized, gin.H{
            "message": "invalid refresh token",
        })
        return
    }

    accessToken, err := util.GenerateAccessToken(*user, []byte(h.environmentVariables.Authentication.JWT_SECRET), 30*time.Minute)
    if err != nil {
        c.JSON(http.StatusInternalServerError, gin.H{
            "message": "failed to generate access token",
        })
        return
    }

    c.JSON(http.StatusOK, gin.H{
        "message": "success",
        "jwt": gin.H{
            "token": accessToken,
        },
    })
}

type RevokeRefreshAccessTokenRequest struct {
    RefreshToken string `json:"refresh_token"`
}

func (h *Handler) RevokeRefreshAccessToken(c *gin.Context) {
    var refreshAccessReq RefreshAccessTokenRequest

    if err := c.ShouldBind(&refreshAccessReq); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{
            "message": "invalid request params",
        })
        return
    }

    err := h.queries.RevokeRefreshToken(c, refreshAccessReq.RefreshToken)
    if err != nil {
        c.JSON(http.StatusUnauthorized, gin.H{
            "message": "failed to revoke refresh token",
        })
        return
    }

    c.JSON(http.StatusNoContent, gin.H{})
}

This handler exposes endpoints for signin, signup, RefreshAccessToken, and RevokeRefreshAccessToken.

Protecting Routes with Middleware

Now let's test our authentication system and create a middleware to protect routes that require authentication:

// internal/ports/http/middleware/auth.go

package middleware

import (
    "net/http"
    "strings"

    "github.com/gin-gonic/gin"
    "github.com/google/uuid"
    "github.com/umohsamuel/authentication-authorization/pkg/env"
    "github.com/umohsamuel/authentication-authorization/pkg/util"
)

func AuthMiddleware(environmentVariables env.EnvironmentVariables) gin.HandlerFunc {
    return func(c *gin.Context) {
        authHeader := c.GetHeader("Authorization")
        if authHeader == "" {
            c.JSON(http.StatusUnauthorized, gin.H{
                "error": "Authorization header required",
            })
            c.Abort()
            return
        }

        parts := strings.Split(authHeader, " ")
        if len(parts) != 2 || parts[0] != "Bearer" {
            c.JSON(http.StatusUnauthorized, gin.H{
                "error": "Invalid authorization format",
            })
            c.Abort()
            return
        }

        tokenString := parts[1]

        claims, err := util.ValidateToken(tokenString, []byte(environmentVariables.Authentication.JWT_SECRET))
        if err != nil {
            c.JSON(http.StatusUnauthorized, gin.H{
                "error": "Invalid or expired token",
            })
            c.Abort()
            return
        }

        userIDStr, ok := claims["sub"].(string)
        if !ok {
            c.JSON(http.StatusUnauthorized, gin.H{
                "error": "Invalid token claims",
            })
            c.Abort()
            return
        }

        userID, err := uuid.Parse(userIDStr)
        if err != nil {
            c.JSON(http.StatusUnauthorized, gin.H{
                "error": "Invalid user ID in token",
            })
            return
        }

        c.Set("userID", userID)

        c.Next()
    }
}

The middleware extracts the JWT token from the Authorization header, validates it, and adds the user ID to the request context. This allows subsequent handlers to access the authenticated user's identity.

Key Things the Auth Middleware Does

Extracting the JWT token from the Authorization header.
Validating the token signature and expiration.
Adding the authenticated user's ID to the request context.
Rejecting requests with invalid or missing tokens.

Connecting the API and Main Application

Let's connect everything together in our API module:

// cmd/api/api.go

package api

import (
    "net/http"
    "time"

    "github.com/gin-contrib/cors"
    "github.com/gin-gonic/gin"
    "github.com/umohsamuel/authentication-authorization/internal/adapters/database/sqlc"
    "github.com/umohsamuel/authentication-authorization/internal/ports/http/handlers/user"
    "github.com/umohsamuel/authentication-authorization/internal/ports/http/middleware"
    "github.com/umohsamuel/authentication-authorization/pkg/env"
)

type Server struct {
    Engine  *gin.Engine
    Env     *env.EnvironmentVariables
    Queries *sqlc.Queries
}

func API(environmentVariables *env.EnvironmentVariables, queries *sqlc.Queries) *Server {

    s := &Server{
        Engine:  gin.Default(),
        Env:     environmentVariables,
        Queries: queries,
    }

    config := cors.DefaultConfig()
    config.AllowAllOrigins = true
    config.AllowMethods = []string{"POST", "GET", "PUT", "OPTIONS"}
    config.AllowHeaders = []string{"Origin", "Content-Type", "Authorization", "Accept", "User-Agent", "Cache-Control", "Pragma"}
    config.ExposeHeaders = []string{"Content-Length"}
    config.AllowCredentials = true
    config.MaxAge = 12 * time.Hour

    s.Engine.Use(cors.New(config))

    s.Engine.Static("/downloads", "tmp")

    s.Health()
    s.User()

    s.Engine.Run()

    return s
}

func (s *Server) Health() {
    s.Engine.GET("/health", middleware.AuthMiddleware(*s.Env), func(ctx *gin.Context) {
        ctx.JSON(http.StatusOK, gin.H{
            "message": "Server Up!",
        })
    })
}

func (s *Server) User() {
    userHandler := user.NewUserHandler(*s.Env, *s.Queries)

    rg := s.Engine.Group("/user")

    rg.POST("/signup", userHandler.SignUp)
    rg.POST("/signin", userHandler.SignIn)
    rg.POST("/refresh", userHandler.RefreshAccessToken)

    // admin in case of revoking access token
    rg.POST("/revoke-refresh", userHandler.RevokeRefreshAccessToken)
}

Now let's connect everything to our main application:

// cmd/main.go

package main

import (
    "github.com/umohsamuel/authentication-authorization/cmd/api"
    "github.com/umohsamuel/authentication-authorization/internal/adapters/database"
    "github.com/umohsamuel/authentication-authorization/internal/adapters/database/sqlc"
    "github.com/umohsamuel/authentication-authorization/pkg/env"
)

var (
    environmentVariables = env.LoadEnvironmentVariables()
)

func main() {

    db := database.NewPool()

    queries := sqlc.New(db)

    api.API(environmentVariables, queries)

}

Run the Application

We can run the application by running:

go run cmd/main.go

You should see among the output, first:

2026/06/11 16:14:11 database created & is reachable

Then lastly:

[GIN-debug] Listening and serving HTTP on :8080

Testing with cURL

curl -X POST http://localhost:8080/user/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "umohsg.alt@gmail.com",
    "password": "SecureP@ssw0rd!"
  }'

We should get the response:

{
  "data": {
    "id": "019eb743-87a6-701b-861a-3339ad2373ce",
    "email": "umohsg.alt@gmail.com",
    "password_hash": "$2a$14$vE3/zq1/WzK3z.uSH4v.9ebvyJfPmAyBZNCLy1Pyr4.ezaX/Zq23q",
    "created_at": {
      "Time": "2026-06-11T16:18:36.709895+01:00",
      "Valid": true
    }
  },
  "message": "user created successfully"
}

Next, let's log in with the newly created user:

curl -X POST http://localhost:8080/user/signin \
  -H "Content-Type: application/json" \
  -d '{
    "email": "umohsg.alt@gmail.com",
    "password": "SecureP@ssw0rd!"
  }'

We should get the response:

{
  "data": {
    "id": "019eb743-87a6-701b-861a-3339ad2373ce",
    "email": "umohsg.alt@gmail.com",
    "password_hash": "$2a$14$vE3/zq1/WzK3z.uSH4v.9ebvyJfPmAyBZNCLy1Pyr4.ezaX/Zq23q",
    "created_at": {
      "Time": "2026-06-11T16:18:36.709895+01:00",
      "Valid": true
    }
  },
  "jwt": {
    "refresh_token": "1fe63ff8-30c8-4666-a53d-951401f71216",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6InVtb2hzZy5hbHRAZ21haWwuY29tIiwiZXhwIjoxNzgxMTkzMDAzLCJpYXQiOjE3ODExOTEyMDMsInN1YiI6IjAxOWViNzQzLTg3YTYtNzAxYi04NjFhLTMzMzlhZDIzNzNjZSJ9.RVQk03jen6HzfHnjXkTiD612gMDrNtFsExWKElWElDg"
  },
  "message": "login successful"
}

Save the access_token and refresh_token from the response for the next steps.

Now let's use the access token to access a protected route:

export ACCESS_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

curl -X GET http://localhost:8080/health \
  -H "Authorization: Bearer $ACCESS_TOKEN"

You should get the response:

{
  "message": "Server Up!"
}

When your access token expires, refresh it using the refresh token you received during login:

export REFRESH_TOKEN="c3d4e5f6-7890-...."

curl -X POST http://localhost:8080/user/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "'$REFRESH_TOKEN'"
  }'

You should get the response:

{
  "jwt": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6InVtb2hzZy5hbHRAZ21haWwuY29tIiwiZXhwIjoxNzgxMTkzMjc0LCJpYXQiOjE3ODExOTE0NzQsInN1YiI6IjAxOWViNzQzLTg3YTYtNzAxYi04NjFhLTMzMzlhZDIzNzNjZSJ9.L6dGe2NbRof2Pjks-83xXZWeFPsqy3Dp06TO2FwNd5Y"
  },
  "message": "success"
}

You can also test an invalid token to see the authentication fail:

curl -X GET http://localhost:8080/health \
  -H "Authorization: Bearer invalid-token"

Then lastly, for whatever suspicious reason, you can revoke a user's refresh token:

export REFRESH_TOKEN="c3d4e5f6-7890-...."

curl -X POST http://localhost:8080/user/revoke-refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "'$REFRESH_TOKEN'"
  }'

And you should get a 204 No Content response.

Conclusion

In this article, we built a secure authentication system in Go, using JWT and PostgreSQL. The system includes secure password hashing, token-based authentication, refresh token support, middleware-protected routes, and bcrypt hashing to prevent brute-force attacks, amongst others. Security headers and best practices were used to protect us against common web vulnerabilities.

You can checkout the source code on Github here: umohsamuel/authentication-and-authorization, play around with it and lmk what you think.

Building a media compression tool with Golang & Gin

Samuel Umoh — Tue, 30 Jun 2026 16:17:29 +0000

You know that moment when a project starts simple but ends up forcing you to learn more about FFmpeg? (we've all had that moment right?) Yeah, welcome to elcompresso, a media compression tool that: accepts a file, compresses it, uploads it to S3, and returns a download link (easy enough right?).

This is how i built it.

Backend

elcompresso is a REST API that:

accepts video, audio, or image uploads
compresses videos/audio with FFmpeg and images with Go’s native image package
stores the result in AWS S3
generates a presigned URL for secure downloads

The entire backend is written in Golang & Gin.

Architecture: Domain, Adapters, Services, and Handlers

The backend follows hexagonal architecture, separating concerns into layers:

backend/
├── cmd/
│   ├── main.go           (entry point, dependency wiring)
│   └── api/api.go        (route setup)
├── internal/
│   ├── adapter/          (external services: compression, storage)
│   ├── service/          (business logic layer)
│   ├── port/http/        (HTTP handlers)
│   └── domain/           (interfaces and value objects)
└── pkg/
    ├── env/              (environment config)
    └── response/         (JSON response wrappers)

Wiring It All Together

In backend/cmd/main.go, we initialize the entire dependency graph:

func main() {
    environmentVariables := env.LoadEnvironment()

    cfg, err := awsConfig.LoadDefaultConfig(context.TODO())
    if err != nil {
        panic(err)
    }
    s3Client := s3.NewFromConfig(cfg)

    adapterDependencies := adapter.AdapterDependencies{
        EnvironmentVariables: environmentVariables,
        Compressor:           &compress.CompressorDependencies{},
        StorageClient:        s3Client,
    }

    adapters := adapter.NewAdapter(adapterDependencies)
    serviceDependencies := service.ServiceDependencies{
        Adapter: adapters,
    }
    services := service.NewService(serviceDependencies)

    r := api.API(services, environmentVariables)
    r.Engine.Run(environmentVariables.Port)
}

Three lines of actual instantiation. Everything else flows from those.

The API Layer

Routes are defined in backend/cmd/api/api.go. We set CORS to allow any origin (reserve your comments mr. security expert), configure file upload memory limits, and expose compression endpoints:

func API(services *service.Services, environment *env.EnvironmentVariables) *Server {
    r := &Server{
        Service:     services,
        Engine:      gin.Default(),
        Environment: environment,
    }

    config := cors.DefaultConfig()
    config.AllowAllOrigins = true
    config.AllowMethods = []string{"POST", "GET", "PUT", "OPTIONS"}

    r.Engine.Use(cors.New(config))
    r.Engine.Static("/downloads", "tmp")
    r.Engine.GET("/health", ...)

    api := r.Engine.Group("/api/v1")
    {
        r.fileCompressRoutes(api)
        r.fileUploadRoutes(api)
    }

    return r
}

Compression Routes

Three POST endpoints at /api/v1/file-compress/{video,audio,image}. Each accepts a multipart form with:

file: the media to compress
quality: a 1-100 quality hint (interpreted differently per format)

Handlers: The Request Pipeline

In backend/internal/port/http/handler/compress.go, the CompressHandler is initialized with dependencies and processes requests. Let's walk through the video handler:

func (h CompressHandler) CompressVideo(c *gin.Context) {
    var fData FormData

    if err := c.ShouldBind(&fData); err != nil {
        response.NewErrorResponse(fmt.Errorf("invalid form data: %v", err.Error())).Send(c)
        return
    }

    if fData.File.Size > 500<<20 {
        response.NewErrorResponse(fmt.Errorf("file too large: max 500MB")).Send(c)
        return
    }

    f, err := fData.File.Open()
    if err != nil {
        response.NewErrorResponse(fmt.Errorf("failed to open file: %v", err)).Send(c)
        return
    }
    defer f.Close()

    fmtedFileName := strings.ReplaceAll(fData.File.Filename, " ", "_")

    req := compress.CompressionRequest{
        Input:    f,
        FileName: fmtedFileName,
        FileType: "video",
        Quality:  fData.Quality,
    }

    res, err := h.adapter.Compressor.Video.Compress(req)
    if err != nil {
        response.NewErrorResponse(fmt.Errorf("failed to compress file: %v", err)).Send(c)
        return
    }

    key, err := h.adapter.Storage.Upload(c.Request.Context(), uuid.New().String()+"_"+fData.File.Filename, res.Output)
    if err != nil {
        response.NewErrorResponse(fmt.Errorf("upload failed: %w", err)).Send(c)
        return
    }

    dUrl, err := h.adapter.Storage.GenerateDownloadURL(c.Request.Context(), key, 24*time.Hour)

    response.NewSuccessResponse("success", gin.H{
        "original_size":   fData.File.Size,
        "compressed_size": res.CompressedSize,
        "download_link":   dUrl,
    }, nil).Send(c)
}

The pattern is identical for audio and image; essentially just parse, validate size, compress, upload, generate download URL, return JSON.

The Compression Adapters

Here's where the magic happens. Each media type has its own compressor implementing the compress.Interface:

type Interface interface {
    Compress(req CompressionRequest) (*CompressionResult, error)
    Supports(fileType FileType, extension string) bool
}

Video Compression

backend/internal/adapter/compress/video/video.go uses FFmpeg to handle .mp4, .mkv, .avi, .mov, .webm, .flv.

func (v *VideoCompressor) Compress(req compress.CompressionRequest) (*compress.CompressionResult, error) {
    ext := filepath.Ext(req.FileName)

    inputFile, err := os.CreateTemp("", "input-*"+ext)
    if err != nil {
        return nil, err
    }
    defer os.Remove(inputFile.Name())

    if _, err := io.Copy(inputFile, req.Input); err != nil {
        return nil, err
    }
    inputFile.Close()

    outputFile, err := os.CreateTemp("", "output-*"+ext)
    if err != nil {
        return nil, err
    }
    defer os.Remove(outputFile.Name())
    outputFile.Close()

    args := v.ffmpegArgs(inputFile.Name(), outputFile.Name(), ext)
    cmd := exec.Command("ffmpeg", args...)
    if err := cmd.Run(); err != nil {
        return nil, fmt.Errorf("ffmpeg failed: %w", err)
    }

    compressed, err := os.Open(outputFile.Name())
    if err != nil {
        return nil, err
    }

    info, _ := compressed.Stat()

    return &compress.CompressionResult{
        Output:         compressed,
        CompressedSize: info.Size(),
    }, nil
}

The FFmpeg args vary by extension:

func (v *VideoCompressor) ffmpegArgs(input, output, ext string) []string {
    switch ext {
    case ".webm":
        return []string{"-y", "-i", input, "-c:v", "libvpx-vp9", "-crf", "30", "-b:v", "0", "-c:a", "libopus", output}
    case ".flv":
        return []string{"-y", "-i", input, "-c:v", "flv1", "-c:a", "mp3", output}
    default:
        return []string{"-y", "-i", input, "-vcodec", "libx264", "-crf", "28", "-c:a", "aac", output}
    }
}

Audio Compression

backend/internal/adapter/compress/audio/audio.go does the same but for audio formats: .mp3, .wav, .flac, .aac, .ogg, .m4a.

Quality is converted to bitrate or sample rate:

func (a *AudioCompressor) ffmpegArgs(input, output, ext string, req compress.CompressionRequest) []string {
    switch ext {
    case ".mp3":
        bitrate := qualityToBitrate(req.Quality)
        return []string{"-y", "-i", input, "-c:a", "libmp3lame", "-b:a", bitrate, output}
    case ".wav":
        sampleRate := qualityToSampleRate(req.Quality)
        return []string{"-y", "-i", input, "-ar", sampleRate, "-sample_fmt", "s16", output}
    case ".flac":
        return []string{"-y", "-i", input, "-c:a", "flac", "-compression_level", "8", output}
    case ".ogg":
        vorbisQ := qualityToVorbis(req.Quality)
        return []string{"-y", "-i", input, "-c:a", "libvorbis", "-q:a", vorbisQ, output}
    case ".m4a", ".aac":
        bitrate := qualityToBitrate(req.Quality)
        return []string{"-y", "-i", input, "-c:a", "aac", "-b:a", bitrate, output}
    default:
        bitrate := qualityToBitrate(req.Quality)
        return []string{"-y", "-i", input, "-b:a", bitrate, output}
    }
}

Image Compression

backend/internal/adapter/compress/image/image.go uses the native image package.

func (i *ImageCompressor) Compress(req compress.CompressionRequest) (*compress.CompressionResult, error) {
    ext := strings.ToLower(filepath.Ext(req.FileName))

    data, err := io.ReadAll(req.Input)
    if err != nil {
        return nil, fmt.Errorf("failed to read input: %w", err)
    }
    originalSize := int64(len(data))

    img, _, err := goimage.Decode(bytes.NewReader(data))
    if err != nil {
        return nil, fmt.Errorf("failed to decode image: %w", err)
    }

    var buf bytes.Buffer

    switch ext {
    case ".jpg", ".jpeg":
        quality := req.Quality
        if quality <= 0 || quality > 100 {
            quality = 60
        }
        err = jpeg.Encode(&buf, img, &jpeg.Options{Quality: quality})
    case ".png":
        encoder := &png.Encoder{CompressionLevel: png.BestCompression}
        err = encoder.Encode(&buf, img)
    default:
        return nil, fmt.Errorf("unsupported image format: %s", ext)
    }

    if err != nil {
        return nil, fmt.Errorf("failed to encode image: %w", err)
    }

    return &compress.CompressionResult{
        Output:         bytes.NewReader(buf.Bytes()),
        OriginalSize:   originalSize,
        CompressedSize: int64(buf.Len()),
        Format:         ext,
    }, nil
}

JPEG gets quality control; PNG gets maximum compression.

Storage: S3 with Presigned URLs

The storage adapter (backend/internal/adapter/storage/storage.go) wraps the AWS SDK:

type Stg struct {
    Client *s3.Client
    Env    env.EnvironmentVariables
}

func NewStorageClient(deps StgDeps) storage.Storage {
    return &Stg{
        Client: deps.Client,
        Env:    deps.Env,
    }
}

func (s *Stg) Upload(ctx context.Context, filename string, file io.Reader) (string, error) {
    key := "compressed/" + filename

    _, err := s.Client.PutObject(ctx, &s3.PutObjectInput{
        Bucket: aws.String(s.Env.S3.AWS_BUCKET),
        Key:    aws.String(key),
        Body:   file,
    })
    if err != nil {
        return "", err
    }

    return key, nil
}

func (s *Stg) GenerateDownloadURL(ctx context.Context, filename string, expiry time.Duration) (string, error) {
    presignClient := s3.NewPresignClient(s.Client)

    req, err := presignClient.PresignGetObject(ctx,
        &s3.GetObjectInput{
            Bucket: aws.String(s.Env.S3.AWS_BUCKET),
            Key:    aws.String(filename),
        }, s3.WithPresignExpires(expiry))

    if err != nil {
        return "", fmt.Errorf("failed to generate presigned URL: %w", err)
    }

    return req.URL, nil
}

Two operations:

Upload: Write to S3 under compressed/{filename}, return the key.
GenerateDownloadURL: Create a presigned URL valid for 24 hours.

This is the AWS SDK V2 approach (yeah, i had my share of headaches hopping from articles to docs).

Configuration

Environment variables are loaded in backend/pkg/env/env.go:

type EnvironmentVariables struct {
    Port                  string
    ProductionEnvironment bool
    ClientDomain          string
    ProjectName           string
    STORAGE_TYPE          string
    S3                    *S3Config
}

type S3Config struct {
    AWS_REGION            string
    AWS_BUCKET            string
    AWS_ACCESS_KEY_ID     string
    AWS_SECRET_ACCESS_KEY string
}

Required at startup:

AWS_REGION
AWS_BUCKET
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY

Optional:

PORT (defaults to :5000)
PRODUCTION_ENVIRONMENT
CLIENT_DOMAIN
PROJECT_NAME

Response Format

Success responses come from backend/pkg/response/response.go:

type SuccessResponse struct {
    StatusCode int         `json:"statusCode,omitempty"`
    Message    string      `json:"message"`
    Data       interface{} `json:"data,omitempty"`
    Metadata   interface{} `json:"metadata,omitempty"`
}

Error responses include the status code, message, and error detail:

type ErrorResponse struct {
    StatusCode   int    `json:"statusCode"`
    Message      string `json:"message"`
    ErrorMessage any    `json:"error"`
}

A successful compression returns:

{
  "message": "success",
  "data": {
    "original_size": 52428800,
    "compressed_size": 15728640,
    "download_link": "https://bucket.s3.region.amazonaws.com/compressed/..."
  }
}

Demo

demo video

Conclusion

Building a media compression backend in Go is pretty straightforward and easy enough.

(If you want to see the full codebase, check the repository. you can also play around with the ui.)

Building Distributed WebSockets with Go, Redis, and RabbitMQ

Samuel Umoh — Tue, 30 Jun 2026 16:15:48 +0000

So you built a WebSocket server. Users connect, they send messages, other users receive them. Life is good. Then someone asks: "What happens when you need to scale to multiple servers?"

And suddenly your nice little connection map is not going to cut it anymore. Because User A is connected to Server 1, User B is connected to Server 2, and your local connection map has no clue the other server even exists.

This is the problem I set out to solve. Let me walk you through how I built a distributed WebSocket system using Go, Redis, and RabbitMQ.

The Problem

With a single server, WebSocket messaging is straightforward. You keep a map of connections, someone sends a message, you look up the recipient in the map, and write to their connection. Done.

But the moment you have multiple server instances (for load balancing, high availability, or just because your app got popular), you have a problem: Server 1 does not know about connections on Server 2. A message sent from a user on Server 1 to a user on Server 2 will just... disappear into the void.

The Solution

The architecture is pretty simple once you see it:

Redis acts as a shared registry. When a user connects to any server, we store userID -> serverID in Redis. Now every server can look up where any user is connected.
RabbitMQ (with topic exchange) handles message routing between servers. Each server subscribes to its own routing key (server.{serverID}). When Server 1 needs to send a message to a user on Server 2, it publishes to RabbitMQ with the routing key server.server-2. Server 2 picks it up and delivers locally.
Local optimization: If both users happen to be on the same server, we skip Redis and RabbitMQ entirely and deliver the message directly.

Here is the flow visually:

User A (Server 1) sends message to User B (Server 2)

1. Server 1 checks: is User B connected locally? No.
2. Server 1 asks Redis: where is User B? -> "server-2"
3. Server 1 publishes to RabbitMQ: key="server.server-2", body=message
4. Server 2 receives from RabbitMQ (subscribed to "server.server-2")
5. Server 2 finds User B in local connections, writes to their WebSocket

Project Structure

Before we get into the code, here is how I organized the project:

cmd/
  main.go              - Entry point, wiring everything together
  api/                 - HTTP routes
  ws/                  - WebSocket handler and message routing logic
config/
  cache/               - Redis client initialization
internal/
  adapter/             - Implementations of domain interfaces
    cache/             - Redis adapter
    queue/             - RabbitMQ adapter
  domain/
    cache/             - Cache interface definition
    queue/             - Queue interface and types
  service/             - Business logic layer
pkg/
  env/                 - Environment variable loading
  util/                - Helpers (server ID, panic on error)

I used a clean architecture style where the domain layer defines interfaces and the adapter layer implements them. This way the WebSocket handler does not care whether the queue is RabbitMQ, Kafka, or carrier pigeons. It just calls Emit() and Recieve().

Step 1: Setting Up the Infrastructure

First things first. We need Redis and RabbitMQ running. I used Docker Compose for this:

version: "3.9"

services:
  redis:
    image: redis:8-alpine
    container_name: app_redis
    restart: unless-stopped
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    command: redis-server --appendonly yes --requirepass ${REDIS_PASSWORD:-secret}
    healthcheck:
      test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD:-secret}", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - app_network

  rabbitmq:
    image: rabbitmq:4-management-alpine
    container_name: app_rabbitmq
    restart: unless-stopped
    ports:
      - "5672:5672"
      - "15672:15672"
    environment:
      RABBITMQ_DEFAULT_USER: ${RABBITMQ_USER:-admin}
      RABBITMQ_DEFAULT_PASS: ${RABBITMQ_PASSWORD:-secret}
      RABBITMQ_DEFAULT_VHOST: ${RABBITMQ_VHOST:-/}
    volumes:
      - rabbitmq_data:/var/lib/rabbitmq
    healthcheck:
      test: ["CMD", "rabbitmq-diagnostics", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - app_network

volumes:
  redis_data:
  rabbitmq_data:

networks:
  app_network:
    driver: bridge

Spin it up with:

docker compose up redis rabbitmq -d

RabbitMQ management UI will be at http://localhost:15672 (guest/guest by default). It is super useful for debugging when you are trying to figure out why your messages are not showing up.

Step 2: Defining the Domain Interfaces

I like to define my interfaces first so I know exactly what capabilities I need before I write any implementation. For the cache (Redis):

package cache

import (
    "context"
    "time"
)

type Interface interface {
    Set(ctx context.Context, key string, value []byte, ttl time.Duration) error
    Get(ctx context.Context, key string) ([]byte, error)
    Delete(ctx context.Context, key string) error
}

Simple. Set a key, get a key, delete a key. That is all we need from Redis for this use case.

For the queue (RabbitMQ), there is a bit more going on. First the types:

package queue

import (
    "context"
    amqp "github.com/rabbitmq/amqp091-go"
)

type ExchangeDeclare struct {
    Name       string
    Kind       string
    Durable    bool
    AutoDelete bool
    Internal   bool
    NoWait     bool
    Args       amqp.Table
}

type QueueDeclare struct {
    Name       string
    Durable    bool
    AutoDelete bool
    Exclusive  bool
    NoWait     bool
    Args       amqp.Table
}

type QueueBind struct {
    Name     string
    Key      []string
    Exchange string
    NoWait   bool
    Args     amqp.Table
}

type Consume struct {
    Queue     string
    Consumer  string
    AutoAck   bool
    Exclusive bool
    NoLocal   bool
    NoWait    bool
    Args      amqp.Table
}

type Publish struct {
    Ctx       context.Context
    Exchange  string
    Key       string
    Mandatory bool
    Immediate bool
    Msg       amqp.Publishing
}

And the interface itself:

package queue

import amqp "github.com/rabbitmq/amqp091-go"

type MessageHandler func(body []byte, mainMsg amqp.Delivery) error

type Interface interface {
    Emit(exchangeConfig ExchangeDeclare, publishConfig Publish) error
    Recieve(exchangeConfig ExchangeDeclare, queueDeclareConfig QueueDeclare, queueBindConfig QueueBind, consumerConfig Consume, handler MessageHandler) error
}

Notice the MessageHandler type. This is the callback that gets called for every message the consumer receives. The handler gets both the message body and the raw amqp.Delivery so it can Ack or Nack the message.

Step 3: Implementing the Adapters

Cache Adapter (Redis)

The Redis adapter is about as simple as it gets:

package cache

import (
    "context"
    "time"

    "github.com/go-redis/redis/v8"
    "github.com/umohsamuel/distributed-sockets/internal/domain/cache"
)

type Cache struct {
    client *redis.Client
}

func NewCacheClient(client *redis.Client) cache.Interface {
    return &Cache{
        client: client,
    }
}

func (c *Cache) Set(ctx context.Context, key string, value []byte, ttl time.Duration) error {
    return c.client.Set(ctx, key, value, ttl).Err()
}

func (c *Cache) Get(ctx context.Context, key string) ([]byte, error) {
    val, err := c.client.Get(ctx, key).Result()
    return []byte(val), err
}

func (c *Cache) Delete(ctx context.Context, key string) error {
    _, err := c.client.Del(ctx, key).Result()
    return err
}

Queue Adapter (RabbitMQ)

This one is more involved. The Emit method declares the exchange and publishes a message. The Recieve method declares the exchange, creates a queue, binds it with routing keys, and starts consuming in a goroutine:

package queue

import (
    "fmt"
    "log"

    amqp "github.com/rabbitmq/amqp091-go"
    "github.com/umohsamuel/distributed-sockets/internal/domain/queue"
)

type Queue struct {
    Conn    *amqp.Connection
    Channel *amqp.Channel
}

func NewQueueClient(conn *amqp.Connection, channel *amqp.Channel) queue.Interface {
    return &Queue{
        Conn:    conn,
        Channel: channel,
    }
}

func (q *Queue) Emit(exchangeConfig queue.ExchangeDeclare, publishConfig queue.Publish) error {
    err := q.Channel.ExchangeDeclare(
        exchangeConfig.Name,
        exchangeConfig.Kind,
        exchangeConfig.Durable,
        exchangeConfig.AutoDelete,
        exchangeConfig.Internal,
        exchangeConfig.NoWait,
        exchangeConfig.Args,
    )
    if err != nil {
        return err
    }

    return q.Channel.PublishWithContext(
        publishConfig.Ctx,
        publishConfig.Exchange,
        publishConfig.Key,
        publishConfig.Mandatory,
        publishConfig.Immediate,
        publishConfig.Msg,
    )
}

func (q *Queue) Recieve(exchangeConfig queue.ExchangeDeclare, queueDeclareConfig queue.QueueDeclare, queueBindConfig queue.QueueBind, consumerConfig queue.Consume, handler queue.MessageHandler) error {
    err := q.Channel.ExchangeDeclare(
        exchangeConfig.Name,
        exchangeConfig.Kind,
        exchangeConfig.Durable,
        exchangeConfig.AutoDelete,
        exchangeConfig.Internal,
        exchangeConfig.NoWait,
        exchangeConfig.Args,
    )
    if err != nil {
        return err
    }

    declaredQueue, err := q.Channel.QueueDeclare(
        queueDeclareConfig.Name,
        queueDeclareConfig.Durable,
        queueDeclareConfig.AutoDelete,
        queueDeclareConfig.Exclusive,
        queueDeclareConfig.NoWait,
        queueDeclareConfig.Args,
    )
    if err != nil {
        return err
    }

    if len(queueBindConfig.Key) < 1 {
        return fmt.Errorf("Queue bind key []string cannot be lesser than 1")
    }

    for _, key := range queueBindConfig.Key {
        err = q.Channel.QueueBind(
            declaredQueue.Name,
            key,
            queueBindConfig.Exchange,
            queueBindConfig.NoWait,
            queueBindConfig.Args,
        )
        if err != nil {
            return err
        }
    }

    msgs, err := q.Channel.Consume(
        declaredQueue.Name,
        consumerConfig.Consumer,
        consumerConfig.AutoAck,
        consumerConfig.Exclusive,
        consumerConfig.NoLocal,
        consumerConfig.NoWait,
        consumerConfig.Args,
    )
    if err != nil {
        return err
    }

    go func() {
        for msg := range msgs {
            if err := handler(msg.Body, msg); err != nil {
                log.Printf("Error handling message: %v", err)
            }
        }
    }()

    return nil
}

A few things to note:

The queue is declared with Exclusive: true, meaning it is tied to this connection and will be auto-deleted when the server disconnects. This is exactly what we want because each server instance should have its own ephemeral queue.
The binding key is a slice of strings because you might want a server to listen on multiple routing keys.
The consumer runs in a goroutine so it does not block the main thread.

Step 4: The WebSocket Handler

This is where the magic happens. The ws package manages local connections, handles incoming messages, and bridges everything together.

Connection Management

package ws

import (
    "context"
    "encoding/json"
    "log"
    "net/http"
    "sync"

    amqp "github.com/rabbitmq/amqp091-go"

    "github.com/gin-gonic/gin"
    "github.com/gorilla/websocket"
    "github.com/umohsamuel/distributed-sockets/internal/domain/cache"
    "github.com/umohsamuel/distributed-sockets/internal/domain/queue"
    "github.com/umohsamuel/distributed-sockets/pkg/response"
)

var upgrader = websocket.Upgrader{
    CheckOrigin: func(r *http.Request) bool {
        return true
    },
}

var clients = make(map[string]*websocket.Conn)
var mutex = &sync.Mutex{}

var cacheClient cache.Interface
var queueClient queue.Interface
var serverID string

The clients map is keyed by userID instead of the raw connection. This way we can look up a user's connection by their ID when we need to deliver a message.

Initialization

func Socket(r *gin.Engine, cache cache.Interface, q queue.Interface, sID string) {
    cacheClient = cache
    queueClient = q
    serverID = sID

    r.GET("/ws", wsHandler)

    startConsumer()
}

We register the WebSocket route and immediately start the RabbitMQ consumer. The consumer starts listening for messages destined for this server right away.

Handling New Connections

func wsHandler(ctx *gin.Context) {
    userID := ctx.Query("user_id")
    if userID == "" {
        response.ErrorResponse{
            StatusCode: http.StatusBadRequest,
            Message:    "user_id required",
        }.Send(ctx)
        return
    }

    conn, err := upgrader.Upgrade(ctx.Writer, ctx.Request, nil)
    if err != nil {
        log.Println("Error upgrading connection: ", err)
        return
    }

    mutex.Lock()
    clients[userID] = conn
    mutex.Unlock()

    cacheClient.Set(context.Background(), "user:"+userID, []byte(serverID), 0)

    log.Printf("User %s connected on server %s\n", userID, serverID)

    go handleConnection(userID, conn)
}

When a user connects, three things happen:

We store their connection in the local clients map
We store user:{userID} -> serverID in Redis so other servers can find them
We start a goroutine to read messages from their connection

Handling Disconnects

func handleConnection(userID string, conn *websocket.Conn) {
    defer func() {
        conn.Close()
        mutex.Lock()
        delete(clients, userID)
        mutex.Unlock()
        cacheClient.Delete(context.Background(), "user:"+userID)
    }()

    for {
        _, message, err := conn.ReadMessage()

        if err != nil {
            break
        }

        handleIncomingMessage(userID, message)
    }
}

When the connection breaks (user closes tab, network dies, whatever), the deferred function cleans up: closes the WebSocket, removes from the local map, and deletes the Redis entry. Now other servers will not try to route messages to a dead connection.

Routing Messages

This is the core logic. When a user sends a message, we need to figure out where the recipient is and get the message there:

type IncomingMessage struct {
    To   string `json:"to"`
    Body string `json:"body"`
}

type QueueMessage struct {
    From string `json:"from"`
    To   string `json:"to"`
    Body string `json:"body"`
}

func handleIncomingMessage(fromUserID string, raw []byte) {
    var msg IncomingMessage
    if err := json.Unmarshal(raw, &msg); err != nil {
        log.Println("Invalid handleIncomingMessage message format:", err)
        return
    }

    mutex.Lock()
    conn, local := clients[msg.To]
    mutex.Unlock()

    if local {
        queueMsg := QueueMessage{From: fromUserID, To: msg.To, Body: msg.Body}
        body, _ := json.Marshal(queueMsg)
        conn.WriteMessage(websocket.TextMessage, body)
        return
    }

    targetServerIDBytes, err := cacheClient.Get(context.Background(), "user:"+msg.To)
    if err != nil {
        log.Printf("User %s not found online\n", msg.To)
        return
    }
    targetServerID := string(targetServerIDBytes)

    queueMsg := QueueMessage{From: fromUserID, To: msg.To, Body: msg.Body}
    body, err := json.Marshal(queueMsg)
    if err != nil {
        log.Println("Failed to Marshall queueMsg:", err)
        return
    }

    err = queueClient.Emit(
        queue.ExchangeDeclare{
            Name:       "messages",
            Kind:       "topic",
            Durable:    true,
            AutoDelete: false,
            Internal:   false,
            NoWait:     false,
            Args:       nil,
        },
        queue.Publish{
            Ctx:       context.Background(),
            Exchange:  "messages",
            Key:       "server." + targetServerID,
            Mandatory: false,
            Immediate: false,
            Msg: amqp.Publishing{
                ContentType: "application/json",
                Body:        body,
            },
        },
    )
    if err != nil {
        log.Println("Failed to emit message:", err)
    }
}

The local shortcut is important. If both users are on the same server, there is zero reason to go through Redis lookup and RabbitMQ. Just deliver directly. Saves network hops and latency.

The Consumer (Receiving Messages from RabbitMQ)

func startConsumer() {
    err := queueClient.Recieve(
        queue.ExchangeDeclare{
            Name:       "messages",
            Kind:       "topic",
            Durable:    true,
            AutoDelete: false,
            Internal:   false,
            NoWait:     false,
            Args:       nil,
        },
        queue.QueueDeclare{
            Name:       "",
            Durable:    true,
            AutoDelete: false,
            Exclusive:  true,
            NoWait:     false,
            Args:       nil,
        },
        queue.QueueBind{
            Key:      []string{"server." + serverID},
            Exchange: "messages",
            NoWait:   false,
            Args:     nil,
        },
        queue.Consume{
            Consumer:  "",
            AutoAck:   false,
            Exclusive: false,
            NoLocal:   false,
            NoWait:    false,
            Args:      nil,
        },

        func(body []byte, mainMsg amqp.Delivery) error {
            var msg QueueMessage
            if err := json.Unmarshal(body, &msg); err != nil {
                mainMsg.Nack(false, false)
                return err
            }

            mutex.Lock()
            conn, exists := clients[msg.To]
            mutex.Unlock()

            if exists {
                err := conn.WriteMessage(websocket.TextMessage, body)
                mainMsg.Ack(false)
                return err
            }
            log.Printf("User %s not found locally\n", msg.To)
            mainMsg.Nack(false, true)
            return nil
        },
    )
    if err != nil {
        log.Println("Failed to start consumer:", err)
    }
}

Each server binds to its own routing key: server.{serverID}. When a message arrives, the handler looks up the target user in the local connections map and writes to their WebSocket.

I set AutoAck: false so we manually acknowledge messages. If the user is found locally, we Ack. If not (maybe they disconnected between the Redis lookup and delivery), we Nack with requeue: true so RabbitMQ can try again or another consumer can pick it up.

Step 5: Wiring It All Together

The main.go ties everything together:

package main

import (
    "fmt"
    "log"

    amqp "github.com/rabbitmq/amqp091-go"
    "github.com/umohsamuel/distributed-sockets/cmd/api"
    "github.com/umohsamuel/distributed-sockets/cmd/ws"
    "github.com/umohsamuel/distributed-sockets/config/cache"
    "github.com/umohsamuel/distributed-sockets/internal/adapter"
    "github.com/umohsamuel/distributed-sockets/internal/adapter/queue"
    "github.com/umohsamuel/distributed-sockets/internal/service"
    "github.com/umohsamuel/distributed-sockets/pkg/env"
    "github.com/umohsamuel/distributed-sockets/pkg/util"
)

var (
    environmentVariables = env.LoadEnvironment()
    serverID             string
)

func init() {
    serverID = util.GetServerID()
    log.Println("Server ID:", serverID)
}

func main() {
    cacheClient := cache.NewCache(environmentVariables)
    defer cacheClient.Close()

    queueConn, err := amqp.Dial(fmt.Sprintf("amqp://guest:%s@%s/", environmentVariables.RabbitMQ.RABBITMQ_PASSWORD, environmentVariables.RabbitMQ.RABBITMQ_ADDR))
    util.FailOnError(err, "Failed to connect to RabbitMQ")
    defer queueConn.Close()

    queueChannel, err := queueConn.Channel()
    util.FailOnError(err, "Failed to open a RabbitMQ channel")
    defer queueChannel.Close()

    queueClient := &queue.Queue{
        Conn:    queueConn,
        Channel: queueChannel,
    }

    adapterDependencies := adapter.AdapterDependencies{
        EnvironmentVariables: environmentVariables,
        CacheClient:          cacheClient,
        QueueClient:          queueClient,
    }

    adapters := adapter.NewAdapter(adapterDependencies)

    serviceDependencies := service.ServiceDependencies{
        Adapter: adapters,
    }

    services := service.NewService(serviceDependencies)

    r := api.API(services, environmentVariables)
    ws.Socket(r.Engine, adapters.CacheImplementation, adapters.QueueImplementation, serverID)
    r.Engine.Run(environmentVariables.Port)
}

Each server gets a unique ID via the SERVER_ID environment variable (or falls back to the machine hostname):

package util

import "os"

func GetServerID() string {
    id := os.Getenv("SERVER_ID")
    if id != "" {
        return id
    }
    hostname, _ := os.Hostname()
    return hostname
}

Step 6: Testing It

To actually see the distribution working, you need to run multiple server instances. Start Redis and RabbitMQ, then open two terminals.

Terminal 1:

SERVER_ID=server-1 PORT=:8080 go run cmd/main.go

Terminal 2:

SERVER_ID=server-2 PORT=:8081 go run cmd/main.go

Now connect WebSocket clients to different servers. Open a browser console and connect as "alice" on server-1:

const ws = new WebSocket("ws://localhost:8080/ws?user_id=alice");
ws.onmessage = (e) => console.log("Received:", e.data);

In another tab, connect as "bob" on server-2:

const ws = new WebSocket("ws://localhost:8081/ws?user_id=bob");
ws.onmessage = (e) => console.log("Received:", e.data);

Now send a message from alice to bob:

ws.send(
  JSON.stringify({
    to: "bob",
    body: "hey bob, can you hear me across servers?",
  })
);

And bob receives:

{
  "from": "alice",
  "to": "bob",
  "body": "hey bob, can you hear me across servers?"
}

That message went from Alice's WebSocket, to Server 1, through Redis (lookup), through RabbitMQ (routing), to Server 2, and finally to Bob's WebSocket. Pretty cool.

Demo

Here is a video showing the whole thing in action with two server instances running side by side:

demo video

Gotchas I Ran Into

A few things that tripped me up while building this:

1. Exchange property mismatch. If you declare an exchange as non-durable and then later change your code to durable, RabbitMQ will reject it with a PRECONDITION_FAILED error. You have to delete the old exchange in the management UI and let the app recreate it. Spent a good amount of time confused by this one.

2. The set vs export thing on Windows. If you are using Git Bash on Windows, set SERVER_ID=server-2 does nothing. You need export or inline it: SERVER_ID=server-2 go run cmd/main.go. I kept wondering why my second server was using the same ID.

3. Redis hostname resolution. When running the app locally but Redis in Docker, you cannot use redis as the hostname (that only works inside the Docker network). Use localhost instead. Obvious in hindsight but it got me.

4. Nacking to the right place. In the consumer, if a user disconnects between the time we looked them up in Redis and the time we try to deliver, the message gets Nacked with requeue. This prevents message loss during that race condition window.

Where to Go From Here

This is a solid foundation, but there are plenty of things you could add (nothing really, "shes perfect"):

Authentication: Right now we just trust the user_id query param. In production you would validate a JWT or session token.
Message persistence: If a user is offline, messages are lost. You could store them in a database and deliver when they reconnect.
Presence system: Use Redis pub/sub or expiring keys to track online/offline status.
Multiple message types: Add a type field to messages and route chat, typing, notification etc. differently.

Final Thoughts

The core idea is honestly pretty simple: use a shared registry (Redis) to know where everyone is, and a message broker (RabbitMQ) to route between servers. The WebSocket part is almost unchanged from a single-server implementation. You just replace the local broadcast channel with a publish to RabbitMQ, and add a consumer that delivers to local connections.

Here's a link to the code on Github umohsamuel/distributed-sockets, if you want to dig through it or run it yourself. Have fun with it.

Adding Impact Effects to Fight Videos Using AI

Samuel Umoh — Tue, 30 Jun 2026 16:12:18 +0000

The goal: take a fight video (anime, boxing, UFC, whatever) and automatically add those dramatic black and white flash effects at the exact moments where someone gets hit. You know, the ones you see in anime edits and fight compilations on TikTok. The kind where the frame goes high contrast and inverted for a split second right when a punch connects.

The idea is simple: upload a video, let AI figure out where the hits land, apply the effects, get the video back.

Here is how I built it.

The Problem

Doing this manually in a video editor is tedious. You have to scrub through the video frame by frame, find every impact moment, add your effect, adjust the timing, repeat. For a 30 second clip with 5 impacts that might take 15 minutes. For longer videos it gets worse.

I wanted a single API call that handles the whole thing.

The Stack

Go with Gin for the HTTP server
FFmpeg for all the video processing (frame extraction, labeling, grid creation, effect application)
Google Gemini (via the genai SDK) for analyzing frames and finding impact moments
PostgreSQL with sqlc for the database layer

The project follows a hexagonal architecture. Ports, adapters, domain, services. Keeps things clean and testable.

Step 1: Extract and Label Frames

The first thing the pipeline does after receiving a video upload is extract frames at 10 frames per second. Each frame gets a visible number burned into the top left corner. This number is how the AI will reference specific frames later.

func ExtractAndLabelFrames(inputPath, outputDir string, sampleRate float64) (*ExtractedFrames, error) {
    if err := os.MkdirAll(outputDir, 0755); err != nil {
        return nil, fmt.Errorf("failed to create output dir: %w", err)
    }

    filterStr := fmt.Sprintf(
        "fps=%g,scale=640:-2,drawtext=text='%%{eif\\:n+1\\:d}':x=10:y=10:fontsize=28:fontcolor=white:borderw=2:bordercolor=black",
        sampleRate,
    )
    outputPattern := filepath.Join(outputDir, "frame_%05d.jpg")

    args := []string{
        "-y",
        "-i", inputPath,
        "-vf", filterStr,
        "-q:v", "3",
        "-f", "image2",
        outputPattern,
    }

    cmd := exec.Command("ffmpeg", args...)
    output, err := cmd.CombinedOutput()
    if err != nil {
        return nil, fmt.Errorf("ffmpeg extract+label error: %w\noutput: %s", err, string(output))
    }

    // ... glob and sort the frame paths, get metadata
}

The drawtext filter here uses %{eif\:n+1\:d} to burn the frame number as an integer. I initially used %{expr\:n+1} but that gave me numbers like 1.000000 instead of just 1. The eif variant formats it as a decimal integer.

For a 30 second video at 10fps, this gives you 300 labeled frames.

Step 2: Arrange Frames Into Grids

Sending 300 individual images to Gemini would be expensive and slow. Instead, I tile the frames into 5x4 grids. That is 20 frames per grid image. A 30 second video now becomes about 15 grid images instead of 300 individual frames.

const (
    gridCols      = 5
    gridRows      = 4
    framesPerGrid = gridCols * gridRows
)

Each grid is built using FFmpeg's concat demuxer and tile filter:

func createSingleGrid(framePaths []string, outputPath string) error {
    // Write a concat list so ffmpeg reads the frames as a sequence
    listPath := outputPath + ".txt"
    var listContent strings.Builder
    for _, p := range framePaths {
        abs, _ := filepath.Abs(p)
        listContent.WriteString(fmt.Sprintf("file '%s'\n", filepath.ToSlash(abs)))
        listContent.WriteString("duration 0.04\n")
    }
    os.WriteFile(listPath, []byte(listContent.String()), 0644)

    tileLayout := fmt.Sprintf("%dx%d", gridCols, gridRows)

    args := []string{
        "-y",
        "-f", "concat",
        "-safe", "0",
        "-i", listPath,
        "-vf", fmt.Sprintf("scale=640:-2,tile=%s", tileLayout),
        "-frames:v", "1",
        "-q:v", "3",
        outputPath,
    }

    cmd := exec.Command("ffmpeg", args...)
    // ...
}

If the last batch has fewer than 20 frames, the tile filter fills the empty cells with black. No special handling needed.

Step 3: Let Gemini Find the Impacts

The grid images get uploaded to Gemini via the File API. Then I send a prompt that tells the model exactly what to look for and what to ignore.

The system prompt is pretty specific:

A key action moment is when two things make significant physical contact:

- A character's motion connecting with another character or object
- A fast-moving object reaching its target
- Two characters or objects colliding with visible force
- A character making contact with a surface with force

And equally specific about what to skip:

- Movement without any contact (running, jumping, flying)
- Preparation or wind-up before contact happens
- Characters standing, posing, talking, or reacting
- The aftermath of contact (character already moving away)
- Black screens or dark frames between scenes
- Scene transitions, fades, cuts between angles

The model returns a simple JSON response:

{ "impacts": [12, 45, 78, 132] }

Just frame numbers. Nothing else. The prompt explicitly says to pick only the 2 to 5 best moments. Quality over quantity.

The grids are uploaded concurrently with a buffered channel to avoid hammering the API:

const maxConcurrent = 5
sem := make(chan struct{}, maxConcurrent)
ch := make(chan result, len(files))

for i, f := range files {
    sem <- struct{}{}
    go func(i int, f llm.File) {
        defer func() { <-sem }()
        uf, err := g.uploadFile(ctx, f)
        ch <- result{index: i, file: uf, err: err}
    }(i, f)
}

Step 4: Apply the Effects

This is the interesting part. The original approach was to re-extract frames from the video at 10fps, apply the effect to the impact frames individually, then stitch everything back together. That worked but the output was choppy because you are reconstructing a video at 10fps regardless of what the original framerate was.

The fix: skip the frame extraction entirely. Convert the impact frame numbers to timestamps and apply the effect filters directly to the original video. FFmpeg has an enable parameter on its filters that lets you turn them on and off based on time.

func BuildImpactVideo(inputPath, outputDir string, impactFrames []int, sampleRate float64, meta *VideoMetadata) (string, error) {
    // Convert frame numbers to time windows
    type timeWindow struct {
        start float64
        end   float64
    }

    var windows []timeWindow
    for _, f := range impactFrames {
        startFrame := f
        if startFrame < 1 {
            startFrame = 1
        }
        endFrame := f + 1

        startTime := float64(startFrame-1) / sampleRate
        endTime := float64(endFrame) / sampleRate
        windows = append(windows, timeWindow{startTime, endTime})
    }

    // Sort and merge overlapping windows
    sort.Slice(windows, func(i, j int) bool { return windows[i].start < windows[j].start })
    var merged []timeWindow
    for _, w := range windows {
        if len(merged) > 0 && w.start <= merged[len(merged)-1].end {
            if w.end > merged[len(merged)-1].end {
                merged[len(merged)-1].end = w.end
            }
        } else {
            merged = append(merged, w)
        }
    }

    // Build enable expression
    var parts []string
    for _, w := range merged {
        parts = append(parts, fmt.Sprintf("between(t,%.3f,%.3f)", w.start, w.end))
    }
    enableExpr := strings.Join(parts, "+")

    filter := fmt.Sprintf(
        "hue=s=0:enable='%s',eq=contrast=3.5:brightness=0.9:enable='%s',curves=all='0/0 0.25/0.1 0.5/0.6 0.75/0.95 1/1':enable='%s'",
        enableExpr, enableExpr, enableExpr,
    )

    // ... run ffmpeg with the filter
}

The enable='between(t,4.000,4.200)' part tells FFmpeg to only apply that filter between 4.0 and 4.2 seconds. The rest of the video passes through untouched. This means the output keeps the original video's native framerate. If your input is 60fps, the output is 60fps. No choppiness.

The effect itself is a chain of three filters:

hue=s=0 removes all color (full desaturation)
eq=contrast=3.5:brightness=0.9 cranks the contrast way up
curves applies a custom tone curve for that punchy look

The Full Pipeline

Putting it all together, the handler orchestrates everything in one request:

func (h *Handler) ExtractFrames(c *gin.Context) {
    // 1. Receive video upload (max 1GB)
    file, err := c.FormFile("video")

    // 2. Extract labeled frames at 10fps
    extracted, err := videoService.ExtractAndLabelFrames(inputPath, framesDir, sampleRate)

    // 3. Create 5x4 grids
    gridPaths, err := videoService.CreateGridImages(extracted.Paths, gridsDir)

    // 4. Upload grids to Gemini
    uploadedFiles, err := h.llm.UploadFiles(llmFiles)

    // 5. Send prompt + grids to Gemini
    llmResponse, err := h.llm.GenerateText(fullPrompt, false, uploadedFiles)

    // 6. Parse the frame numbers from the response
    var impactResponse domainVideo.ImpactResponse
    json.Unmarshal([]byte(jsonStr), &impactResponse)

    // 7. Build the output video with effects applied
    outputPath, err := videoService.BuildImpactVideo(inputPath, tempDir, impactResponse.Impacts, sampleRate, meta)

    // 8. Return download URL
    response.NewSuccessResponse("Impact video generated successfully", gin.H{
        "download_url": downloadURL,
        "impacts":      impactResponse.Impacts,
        "llm_cost":     llmResponse.Dollars,
    }, nil).Send(c)
}

Upload a video, get back a download URL. The response also includes which frame numbers were detected and how much the Gemini API call cost.

Example Output

Before (original):

before video

After (with impact effects):

after video

Things I Ran Into

FFmpeg escaping on Windows. The filter strings have nested single quotes (the enable='...' and curves=all='...' both use them). On Windows, the command line argument parsing was mangling them. I ended up writing the filter to a file and using -filter_script:v to load it, which bypasses all the escaping issues.

Label formatting. FFmpeg's drawtext expression %{expr\:n+1} gives you 1.000000. You need %{eif\:n+1\:d} for integer formatting.

Grid rendering. I initially tried using FFmpeg's xstack filter to arrange frames into grids. It was unreliable. Switching to the concat demuxer plus the tile filter was way more straightforward.

Gemini content filtering. Google's safety filters can block fight/combat content at the infrastructure level, even with all safety settings set to off. This is a policy level thing, not something you can override via the API. Worth knowing if you are working with action content.

Thinking config compatibility. gemini-2.5-pro does not support ThinkingConfig. Only the preview variants do. If you set ThinkingLevel: ThinkingLevelHigh on the non-preview model, you get a 400 error.

Try It Out

The full source code is on GitHub: github.com/umohsamuel/impact

You need Go, FFmpeg, and a Google Gemini API key to run it locally.

git clone https://github.com/umohsamuel/impact.git
cd impact
go mod download
# set up your .env
go build -o ./tmp/main.exe ./cmd
./tmp/main.exe

Then hit the endpoint:

curl -X POST http://localhost:5000/api/v1/generate-impact-frames \
  -F "video=@your-video.mp4"