DEV Community: medunes

Your Connection is Not Private: What Your Browser Is Warning You About?

medunes — Wed, 21 Jan 2026 14:09:00 +0000

We’ve all been there. You are building a local web application, you fire up https://localhost to test a new feature, and bam! your browser slaps you with a giant red warning: "Your connection is not private."

As a developer, your first instinct is frustration. "I know it's not private! It's running on my laptop! Just let me in!" You click Advanced -> Proceed to localhost (unsafe) and move on.

But have you ever stopped to ask: Why does the browser care so much? How does it actually "know" who is trustworthy and who isn't? And why is "fixing" this properly so much more complicated than just generating a file?

The answer lies in a rigid, bureaucratic hierarchy known as the Chain of Trust. Let’s dismantle it, layer by layer, starting from that annoying red warning.

Level 1: The "Handwritten ID" Problem (Self-Signed vs. CA)

When you generate a certificate locally (using OpenSSL or a script), you create two files: a Private Key (kept secret) and a Certificate (public). You configure your server to use them, but the browser still hates it. Why?

The browser isn't saying your encryption is bad. The math works fine; your traffic is encrypted. The browser is saying your identity is unverified.

Imagine trying to enter a high-security government building.

Real World: You show a Passport. The guard trusts it because the Government issued it.
Localhost: You show a napkin where you scribbled "I am Admin". The guard (Browser) rejects it.

When you create a "Self-Signed Certificate," you are essentially being your own government. You are vouching for yourself. The browser’s job is to protect the user from imposters, so it treats any ID not issued by a known "Government" as a fake.

The Fix:
To make the warning go away, you have to perform a "manual override." When you import your certificate into your OS (Windows Cert Store) or Linux (/etc/ssl/certs), you are effectively telling your computer: "I personally trust this Napkin ID as much as a Passport."

Level 2: The Anatomy of Trust (How "Belief" Works)

This begs the question: Who are these "Governments" the browser actually trusts?

If you dig into your operating system (or browser settings), you will find a folder or database called the Trust Store. This is a pre-installed list of about 100-150 organizations known as Root Certificate Authorities (Root CAs) companies like DigiCert, GlobalSign, and Let's Encrypt.

When you visit google.com, the browser performs a cryptographic background check:

The Handshake: Google presents its Certificate.
The Signature Check: The browser looks at the "digital signature" on the certificate. A signature is created by taking the certificate's data, hashing it, and encrypting that hash with an Issuer's Private Key.
The Verification: The browser decrypts the signature using the Issuer's Public Key (which it finds in your local Trust Store).

If the math adds up, it proves two things:

Integrity: The certificate hasn't been altered.
Authenticity: It was definitely issued by a Trusted Authority.

And if you have ever wondered what does a certificate concretely contain after all, let's say if you opened the certificate file in a text editor, it would show a block of text starting with

-----BEGIN CERTIFICATE-----

If you decoded it (viewed its details), you would see various information, but most importantly three critical things:

Identity: "This cert belongs to www.example.com."
Server's Public Key: "The public key for www.example.com is [Key Data Here]."
Other Meta Data: "Ex: This cert is valid from Jan 1st to April 1st."

The Certificate Authority (CA), like Let's Encrypt, signs a data block called the TBSCertificate (To-Be-Signed Certificate).

The Signature Logic is simple: Let's Encrypt takes that entire block of text, hashes it (e.g., SHA-256), and then encrypts that hash with their Private Key. That encrypted hash is the "Signature" attached to the bottom of the CRT file.

Now as your browser/OS has the public key of the authority, it can decrypt it (this is how asymmetric cryptography works) and get an evidence this is only possible by the owner of the private key that corresponds to this public key, hence the authenticity!

Level 3: The Intermediate Gap (Why R3?)

Here is where developers often get confused. If you inspect the certificate for a site like Wikipedia, you won't see "Signed by Root CA." You’ll see it was signed by something like "R3" or "Let's Encrypt Authority X3."

Question: Wait, my browser trusts the Root. It doesn't know who "R3" is. Why does this work?

This is the Intermediate CA. The Root Authority almost never signs websites directly. Instead, they use a delegation system:

The Root CA (Offline, highly secure) signs the Intermediate CA.
The Intermediate CA (Online, automated) signs Your Website.

When your server responds to a user, it doesn't just send its own certificate. It sends a Certificate Bundle (or "Chain") that includes the Intermediate cert.

The browser follows the breadcrumbs:

"I see example.com. It was signed by R3."
"I see R3. It was signed by ISRG Root X1."
"I know ISRG Root X1! It's in my local Trust Store. Access Granted."

But why go through this trouble? Why not just use the Root?

Level 4: The "Blast Radius" (Risk Management)

This is the most critical architectural decision in web security.

Question: Why don't we just use the Root Key to sign everything? It would be simpler.

Answer: Because if the Root Key is stolen, the internet breaks.

The Root Key is the "Crown Jewels." It is usually kept on a computer that is physically air-gapped (never connected to the internet), stored in a secure vault. It is only powered on rarely, under strict supervision, to sign a new Intermediate.

If a hacker steals the Intermediate Key (R3):

The Authority revokes R3.
They spin up a new Intermediate (R4).
Websites update their config to use R4.
Crucially: Users don't have to do anything. Their browsers still trust the Root, so they automatically trust R4.

If a hacker steals the Root Key:

The Root must be revoked.
Every device on the planet (phones, laptops, smart fridges) needs a System Update to remove the old Root and add a new one.
The Consequence: Older devices that no longer receive updates (e.g., an old Android phone) would be permanently bricked. They would never trust the new Root and would lose access to the secure internet forever.

Level 5: The Loophole (Revocation & The "Bricked" vs. "Vulnerable" Trade-off)

You might argue: "If an Intermediate is stolen, old devices won't know it was revoked anyway, so they will trust the hacker. Isn't that just as bad?"

You are right to spot this flaw. An old device that doesn't get updates won't know "Intermediate R3" has been blacklisted. It will trust the hacker's site.

However, the industry prefers Vulnerability over Obsolescence.

Scenario A (Root Breach): The old phone cannot connect to google.com at all. It is useless e-waste.
Scenario B (Intermediate Breach): The old phone can connect to google.com. It might also connect to a hacker's site if tricked, but the device still functions for legitimate use.

Modern browsers mitigate this using OCSP (Online Certificate Status Protocol). Instead of downloading a massive list of banned certs, the browser can ping the Authority in real-time: "Hey, is this certificate still valid?" This allows us to revoke trust instantly without needing to push a full system update to the user.

Summary

The "Not Secure" warning isn't just an annoyance; it's the tip of an iceberg that keeps the internet from descending into chaos.

Trust Stores act as the anchor (The "Governments").
Signatures prove identity, not just encryption.
Intermediates protect the Root Keys from theft.
Revocation protocols try to balance security with usability.

Next time you bypass that warning on localhost, remember: you're momentarily stepping out of the rigid bureaucracy that keeps your banking data safe.

We don't do that here: How to Go the Go way - Part 1

medunes — Sat, 03 Jan 2026 21:42:16 +0000

If you are like me transitioning to Go from another tech-stack or ecosystem, you might have found yourself unarmed from some of your most powerful tactics and weapons you gathered throughout your career. In simpler words, you would hit a wall on which is written: "we don't do this here :)."

Some of the best practices you learned in Java/Spring OOP or PHP/Symfony would be considered anti-patterns and red flags in Go. What to do? Not many options, indeed. You only have to "go the Go way."

Here we explain a common confusion for the newcomer: the straightforward dependency injection is not (from what I could research at least) often the very welcome within the idiomatic Go republic.

Disclaimer: There might be no single place to dictate to you "we don't do this here," but based on a couple of widely used open-source projects, language authors and maintainers, and famous blog posts you might conclude this.

How they do it the Go way?

Have you ever came across this code style, and had couple question marks itching your brain for a while?

type UserAggregator struct {
    profileFetcher Fetcher
    ordersFetcher  Fetcher
    timeout        time.Duration
    logger         *slog.Logger
}

type Option func(*UserAggregator)

func WithTimeout(d time.Duration) Option {
    return func(u *UserAggregator) {
        u.timeout = d
    }
}

func WithLogger(l *slog.Logger) Option {
    return func(u *UserAggregator) {
        u.logger = l
    }
}

func NewUserAggregator(p Fetcher, o Fetcher, opts ...Option) *UserAggregator {
    // Default configuration
    agg := &UserAggregator{
        profileFetcher: p,
        ordersFetcher:  o,
        timeout:        5 * time.Second,
        logger:         slog.Default(),
    }

    for _, opt := range opts {
        opt(agg)
    }
    return agg
}

I assume you got that moment of confusion: "Isn't this just a Builder or Setters with extra steps?"

You are spotting a pattern correctly. The code snippet above is known as the Functional Options Pattern (popularized by Dave Cheney and Rob Pike).

To answer your question: Yes, this is analogous to the Builder pattern or Setter injection in OOP, but with a twist regarding mutability and safety.

In a typical OOP container (such as Spring Boot or Symfony), you often have two phases:

Instantiation: The object is created (often with a no-arg constructor).
Hydration (Setters): The container calls setLogger(), setTimeout(), etc.

The Go "Anti-Pattern" concern here is state validity.
If you use setters (u.SetLogger(l)), you introduce a period of time where the object exists but is incomplete (e.g., the logger is nil). You also make the object mutable: anyone can change the logger halfway through the program's lifecycle.

The Functional Options pattern allows you to simulate a constructor that accepts optional parameters while ensuring that once the function returns, the object is immutable, fully configured, and ready to use.

The Alternatives: Why not `New(a, b, c)` or `New(Config)`?

Have you just wondered why Go ditches the explicit configuration object. Actually, Go doesn't ditch it entirely (you will see New(Config) in standard libraries), but Functional Options are preferred for libraries for at least the following two reasons:

1. The "Massive Constructor" Problem

New(logger, timeout, db, cache, metrics, ...)
This is brittle. If you add a new dependency, you break every caller in your code-base.

2. The `New(Config)` Problem

Passing a struct, like New(Config{Timeout: 10s}), seems clean, but it has hidden edges:

Ambiguity of Zero Values: If you pass Config{Timeout: 0}, does that mean "No Timeout" or "Default Timeout"? In Go, 0 is the default value for integers, It's hard to distinguish "I forgot to set this" from "I explicitly want 0". There isn't the luxury of the "nullable" parameter as you'd face in PHP as ?int
Boilerplate: If you only want to change one setting, you still have to construct the struct, potentially dealing with pointers to optional fields to distinguish nil from 0.

The Java/OOP Equivalent (The Builder Pattern)

In Java/Spring, to achieve the same "safety" (immutability + optional parameters), you wouldn't typically use raw Setters; you would use a Builder.

// Usage
UserAggregator u = UserAggregator.builder()
    .timeout(Duration.ofSeconds(10))
    .logger(myLogger)
    .build();

// Inside the class
public class UserAggregator {
    private final Duration timeout; // final = immutable, like Go's approach
    private final Logger logger;

    private UserAggregator(Builder b) {
        this.timeout = b.timeout != null ? b.timeout : Duration.ofSeconds(5); // Default handling
        this.logger = b.logger;
    }
    // ...
}

Comparison: Go achieves this using functions as first-class citizens, whereas Java requires a separate inner class (Builder) to hold the temporary state.

The PHP/Symfony Equivalent (Options Resolver)

In PHP, specifically Symfony, this is often handled via the OptionsResolver component because PHP lacks named arguments (historically) and strict typing (historically).

// Usage
$aggregator = new UserAggregator([
    'timeout' => 10,
    'logger' => $logger
]);

// Inside the class
class UserAggregator {
    public function __construct(array $options = []) {
        $resolver = new OptionsResolver();
        $resolver->setDefaults(['timeout' => 5]);
        $resolver->setRequired(['logger']);

        $config = $resolver->resolve($options);
        // ... set properties
    }
}

Comparison: This is much looser. The Go pattern provides compile-time safety (you can't pass a "timout" typo option), whereas the PHP array approach needs runtime validation.

Summary

The Functional Options pattern is idiomatic in Go because it aligns with the language's philosophy:

Explicit over implicit, as this pattern often won't rely on magical DI hydration, and you witness the override with nude eyes.
Stay away from the million dollar mistake and avoid nil pointer exceptions that occur when you forget to call a Setter in OOP. The New function guarantees a valid object.
"Infinite" extensibility: you can add WithDatabase() later without breaking existing code that calls New(). The options logic is delegated and encapsulated within each corresponding function.

Demystifying Go Mutex: How Synchronization Works Under the Hood

medunes — Wed, 27 Aug 2025 13:17:17 +0000

Have you ever wondered what really happens behind the scenes when you use a sync.Mutex in your Go code? It feels like magic: you call Lock(), and somehow, all other goroutines patiently wait their turn. But it's not magic, it's a clever collaboration between the Go runtime scheduler and the CPU itself.

Let's peel back the layers and see how this elegant dance of synchronization actually works.

The Code We'll Analyze

To ground our discussion, we'll use this classic concurrent counter program. The goal is simple: have 10,000 goroutines all increment a single shared variable x. Without a mutex, this would be a chaotic race condition. With it, the final result is a perfect 10,000.

package main

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

var x int
var m sync.Mutex

// inc increments our shared counter safely.
func inc(wg *sync.WaitGroup) {
    defer wg.Done()
    m.Lock()
    x++
    m.Unlock()
}

func main() {
    var wg sync.WaitGroup
    wg.Add(10000)
    for i := 0; i < 10000; i++ {
        go inc(&wg)
    }
    wg.Wait()
    fmt.Println("Final value of x:", x)
}

The sync.Mutex is the hero here. But how does it enforce this order at the machine level?

Busting a Common Myth: It's Not Memory Protection

First, let's clear up a common misconception. A Mutex does not work by telling the hardware to protect a region of memory. The CPU has no idea what a mutex is. The protection is a cooperative software agreement. Any buggy code could technically ignore the lock and access x directly, causing a race condition.

The "magic" isn't in hardware memory barriers, but in a sophisticated two-phase strategy built on a single, powerful CPU feature: atomic operations.

The Real Magic: A Two-Phase Strategy

Go's mutex is designed for high performance. It assumes that locks are usually "uncontended" (not held by another goroutine). So, it uses a "spin-then-park" approach.

Phase 1: The Fast Path (Atomic Optimism)

When a goroutine calls m.Lock(), it first tries the fast path.

It uses an atomic CPU instruction, like Compare-And-Swap (CAS). On x86, this might be the LOCK CMPXCHG instruction.
This instruction does one indivisible thing: "Check the mutex's state variable in memory. If it's 0 (unlocked), set it to 1 (locked) and tell me I succeeded."
If it succeeds, the goroutine has acquired the lock in just a few nanoseconds without any help from the OS kernel. It continues executing.

If the lock is already held, the CAS fails. But the goroutine doesn't give up immediately. It "spins" for a very short time, retrying the atomic CAS in a tight loop. This is an optimistic bet that the lock will be released very soon, avoiding the much higher cost of involving the scheduler.

Phase 2: The Slow Path (A Little Nap)

If spinning for a few cycles doesn't work, the goroutine gives up on the fast path and takes the slow path.

It adds itself to a wait queue specific to that mutex.
It calls into the Go scheduler, which parks the goroutine.
"Parking" means the goroutine is put to sleep. It's removed from the runnable queue and won't consume any CPU time until it's woken up. The OS thread is now free to run a different, ready-to-go goroutine.

This is far more efficient than the goroutine just "skipping its round" and trying again later. It yields the CPU completely.

Visualizing the Goroutine Dance

This diagram illustrates the lifecycle of goroutines interacting with the mutex.

A Step-by-Step Walkthrough

Let's trace our 10,000 goroutines with this new understanding.

G1 Takes the Lock (Fast Path): The scheduler picks the first goroutine, G1. It calls m.Lock(), executes a successful CAS, and acquires the lock. It now begins to execute x++.
G2 Tries and Parks (Slow Path): Before G1 finishes, the scheduler might run G2. G2 calls m.Lock(), but its atomic CAS fails because the lock state is 1. After a brief spin, G2 gives up, adds itself to the mutex's wait queue, and the scheduler parks it. G2 is now asleep.
G3, G4... also Park: The same thing happens to G3, G4, and any other goroutine that runs before G1 is done. They all try the lock, fail, and end up in the wait queue, sleeping peacefully.
G1 Unlocks and Wakes Another: Eventually, G1 gets CPU time again. It finishes x++ and calls m.Unlock(). The Unlock function atomically sets the lock state back to 0 and, crucially, notifies the scheduler that there are goroutines in the wait queue.
G2 Wakes Up: The scheduler takes one goroutine from the wait queue,say, G2, and moves it back to the runnable queue. When G2 is scheduled next, it will retry its m.Lock() call, which will now succeed on the fast path. It will then increment x, unlock the mutex, and wake up the next in line.

This orderly process continues until all 10,000 goroutines have had their turn.

A Simple Analogy: The Single Bathroom Key

Think of the critical section (x++) as a public bathroom that can only hold one person.

The Mutex (m) is the single key to the bathroom.
Fast Path: You walk up and the door is open. You take the key, go in, and lock it.
Slow Path: You arrive and the door is locked. You don't just walk away and come back randomly. You form an orderly queue and wait. When the person inside comes out, they give the key directly to the first person in line.

This queueing is exactly what the Go scheduler does, ensuring fairness and efficiency.

Conclusion

The beauty of sync.Mutex is this seamless collaboration. The CPU provides the foundational guarantee with atomic operations, ensuring that changing the "locked" flag is an indivisible action. The Go Scheduler provides the intelligence, efficiently parking and waking goroutines so that no CPU time is wasted on waiting.

Next time you type m.Lock(), you can appreciate the sophisticated dance happening underneath, a dance that makes your concurrent programs correct, efficient, and robust.

Creating a REST API in Go with Gin: A Pragmatic, Spec-First Guide

medunes — Wed, 06 Aug 2025 17:16:55 +0000

Let's cut to the chase. You need to build a REST API in Go. You want it to be modern, maintainable, and built following best practices: this is a hands-on guide to doing it the right way.

The Problem: Specification Hell or Heaven?

So, you're starting a greenfield project. The eternal question arises: do you write the code first and then generate the API specification (like OpenAPI/Swagger)? Or do you write the spec first and then generate the code?

This isn't just a philosophical debate. It has real-world consequences:

Code-First: You move fast initially, but the spec often becomes an afterthought. It drifts from the actual implementation, leading to confused frontend teams, incorrect documentation, and integration nightmares.
Spec-First: This seems slower upfront, but it forces you to think through your API design. The spec becomes the source of truth.

Our Approach: We're going all-in on spec-first. Why? Because it unlocks massive benefits. By creating an openapi.yaml file first, we establish a contract. Other teams (frontend, QA, other backend services) can immediately use this contract to generate mock servers and start their work. They aren't blocked by our implementation. We are all working in parallel, protected by a clear, agreed-upon interface.

This also sets us up to leverage powerful code generators. We can automatically create server stubs, data models, and even client-side code, all from that single YAML file. This isn't just efficient; it's a key to long-term maintainability.

The Plan: Spec -> Generate -> Implement

Here’s how we're going to tackle this:

Define the API Contract: We'll write an openapi.yaml file. This is our single source of truth.
Structure the Project: We'll lay out our Go project in a clean, idiomatic way.
Generate Code: Using oapi-codegen, we'll generate the server scaffolding and data types directly from our YAML file.
Implement Business Logic: We'll write the actual logic for our API endpoints.
Automate with Make: We'll use a Makefile to streamline the code generation process, making it a repeatable, one-command step.

Project Structure: Go Standard Layout

A good project structure is crucial for maintainability. We'll follow a layout that is common in the Go community and promotes a clean separation of concerns.

/my-api
├── cmd/
│   └── api/
│       └── main.go         # Entry point of our application
├── docs/
│   └── openapi.yaml        # Our API specification (source of truth)
├── internal/
│   ├── api/
│   │   ├── openapi_server.gen.go  # Generated server code
│   │   └── openapi_types.gen.go   # Generated type definitions
│   └── handler/
│       └── handler.go      # Our business logic implementation
├── go.mod
├── go.sum
└── Makefile

cmd/api/main.go: This is where our application starts. Its job is to initialize the database connections, set up the Gin router, and wire everything together.
docs/openapi.yaml: The heart of our spec-first approach.
internal/: This is a special directory in Go. Code inside internal can only be imported by code within the same project, preventing other projects from accidentally depending on our internal logic.
- api/: This package will hold the code generated by oapi-codegen. We keep it separate to make it clear what is machine-generated vs. hand-written.
- handler/: This is where we'll write the actual implementation for our API endpoints (the "business logic").
Makefile: A simple script to automate our development tasks, like code generation.

Step 1: Define the API with OpenAPI 3

First, let's create our API specification in docs/openapi.yaml. We'll define two simple endpoints: one to get a list of users and another to get a list of products.

# docs/openapi.yaml
openapi: 3.0.3
info:
  title: "Simple API"
  version: "1.0.0"
paths:
  /users:
    get:
      summary: "Get a list of users"
      operationId: "getUsers"
      responses:
        '200':
          description: "A list of users"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
  /products:
    get:
      summary: "Get a list of products"
      operationId: "getProducts"
      responses:
        '200':
          description: "A list of products"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
    Product:
      type: object
      properties:
        sku:
          type: string
        name:
          type: string
        price:
          type: number
          format: float

Step 2: Automate Code Generation with a `Makefile`

Now for the magic. We'll use oapi-codegen to read our YAML file and generate Go code. With Go 1.24+, we can manage tools like this directly in our go.mod file, which is fantastic for ensuring consistent builds.

First, add the tool to your project:

go get -u github.com/gin-gonic/gin
go get -tool github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest

This command does two things:

Adds gin as a project dependency.
Adds oapi-codegen as a tracked tool in go.mod.

Now, create the Makefile:

# Makefile
.PHONY: gen-code

gen-code:
    @echo "--- Generating OpenAPI server and types ---"
    @go tool oapi-codegen --config=codegen.yaml docs/openapi.yaml

.PHONY: tidy
tidy:
    @go mod tidy

For more complex projects, using a configuration file for oapi-codegen is cleaner. Create codegen.yaml:

# codegen.yaml
package: api
generate:
  - types
  - gin
output: internal/api/openapi.gen.go

This configuration tells the tool to generate the types and gin server code into a single file. Now, running make gen-code will generate our server interface and all the required structs into internal/api/openapi.gen.go.

Step 3: Implement the Business Logic

The generated code provides us with a ServerInterface. Our job is to create a struct that implements this interface. This is where our actual business logic lives.

Create the file internal/handler/handler.go:

// internal/handler/handler.go
package handler

import (
    "net/http"

    "my-api/internal/api" // Import the generated package

    "github.com/gin-gonic/gin"
)

// Server implements the generated ServerInterface.
type Server struct{}

// Make sure we conform to the interface
var _ api.ServerInterface = (*Server)(nil)

// getUsers implements the business logic for the /users endpoint.
func (s *Server) GetUsers(c *gin.Context) {
    users := []api.User{
        {Id: 1, Name: "Alice"},
        {Id: 2, Name: "Bob"},
    }
    c.JSON(http.StatusOK, users)
}

// getProducts implements the business logic for the /products endpoint.
func (s *Server) GetProducts(c *gin.Context) {
    products := []api.Product{
        {Sku: "A123", Name: "Laptop", Price: 1200.50},
        {Sku: "B456", Name: "Mouse", Price: 25.00},
    }
    c.JSON(http.StatusOK, products)
}

Notice how we're using the api.User and api.Product structs that were generated for us. If we change the spec and regenerate, the compiler will tell us exactly what we need to update in our handler. This is a remarkable win for maintainability.

Step 4: Wire It All Together

Finally, let's write our main.go to start the server.

// cmd/api/main.go
package main

import (
    "my-api/internal/api"
    "my-api/internal/handler"

    "github.com/gin-gonic/gin"
)

func main() {
    // Create our handler which satisfies the generated interface
    myHandler := &handler.Server{}

    // Set up the Gin router
    r := gin.Default()

    // Use the generated RegisterHandlers function to wire up our handlers
    // to the Gin router.
    api.RegisterHandlers(r, myHandler)

    // Start the server
    r.Run(":8080")
}

The api.RegisterHandlers function is another powerful piece of the generated code. It takes care of all the boilerplate for routing requests to the correct handler methods.

Conclusion: A Maintainable, Scalable Foundation

And that's it! You now have a fully functional, spec-driven REST API.

Let's recap the benefits of this approach:

Single Source of Truth: openapi.yaml is the contract. All code is generated or validated against it.
Parallel Development: Frontend and backend teams can work simultaneously, unlocked by the API spec.
Type Safety: Go's strong type system, combined with code generation, catches errors at compile time, not runtime.
Reduced Boilerplate: oapi-codegen handles the tedious work of routing and data model creation.
Consistency: The Makefile and go tool support ensure that every developer on your team generates code the exact same way.

This spec-first methodology provides a robust foundation for building APIs in Go that are not only fast and efficient but also a pleasure to maintain and scale over time. Happy coding!

References

Build C Projects Like a Pro: A Guide to Idiomatic Makefiles

medunes — Tue, 05 Aug 2025 07:16:35 +0000

If you've ever worked with C, you've likely encountered the rite of passage that is the Makefile.
For many, it's a cryptic, frustrating file full of strange symbols and tab-sensitive lines. But what if you could not only understand it but wield it to create clean, professional, and scalable C projects?
This guide is for you. We'll move beyond simple, single-file compilation and build a complete, idiomatic Makefile from scratch. We'll break down every line and concept so you understand not just what it does, but why it's a best practice.
By the end, you'll have a powerful template you can adapt for all your future C projects.

The Project: A Simple Frequency Counter

To make this practical, we'll build a real command-line tool. Our program, freq-counter, will take a filename as an argument and count the frequency of each alphabet character in that file.

Our project will be structured professionally with separate directories for source code, headers, and tests:

main.c: Handles command-line arguments and file I/O.
freq.c: Contains the core logic for counting character frequencies.
freq.h: The header file declaring our frequency-counting functions.
test_freq.c: A test file to verify that our counting logic is correct.

The Makefile: An Overview

We will create a Makefile that handles everything:

Configuration: Easily change project names, directories, and compiler flags.
Automatic Discovery: Automatically find all .c source files without manual updates.
Build Targets: Compile the main program and a separate test executable.
Lifecycle Management: Install, uninstall, and clean the project with simple commands.

Let's dive in.

The Makefile Breakdown

Part 1: Configuration

This first section contains all the variables we need. Centralizing them here makes the project easy to configure.

# ---- configuration ---------------------------------------------------------
BIN       := freq-counter
PREFIX    ?= /usr/local

SRC_DIR   := src
INC_DIR   := include
TEST_DIR  := tests

SRCS      := $(wildcard $(SRC_DIR)/*.c)
OBJS      := $(SRCS:.c=.o)
TEST_SRCS := $(wildcard $(TEST_DIR)/*.c)
TEST_OBJS := $(TEST_SRCS:.c=.o)
CC        ?= cc
CFLAGS    := -std=c11 -Wall -Wextra -I$(INC_DIR) -O2
LDLIBS    :=

BIN := freq-counter
- What it does: Assigns the name of our final program, "freq-counter," to the BIN variable.
- Why it does this (The Idiom): It defines the executable's name in one place. If you want to rename your project, you only need to change this line. := assigns the value immediately.
- Your Takeaway: Always define output filenames as variables at the top of your file.
PREFIX ?= /usr/local
- What it does: Conditionally assigns /usr/local to the PREFIX variable.
- Why it does this (The Idiom): The ?= operator means "assign this value ONLY if PREFIX is not already defined." This is a powerful idiom that allows users to easily override the installation path from the command line (e.g., make install PREFIX=/opt/custom).
- Your Takeaway: Use ?= for any variable you want to allow a user to easily customize, especially installation paths.
SRC_DIR, INC_DIR, TEST_DIR
- What it does: Defines variables for the names of our source, include, and test directories.
- Why it does this (The Idiom): This avoids hardcoding directory names throughout the Makefile, making the structure configurable and the script cleaner.
- Your Takeaway: Define your directory layout as variables.
SRCS := $(wildcard $(SRC_DIR)/*.c)
- What it does: Creates a list of all files ending in .c inside the src directory and assigns this list to the SRCS variable.
- Why it does this (The Idiom): wildcard is a make function that expands shell globbing patterns. This is the idiomatic way to get a list of source files. It automatically finds new .c files as you add them.
- Your Takeaway: This is the best practice for discovering source files.
OBJS := $(SRCS:.c=.o)
- What it does: It takes the list of source files (e.g., src/main.c src/freq.c) and creates a corresponding list of object file names by replacing the .c suffix with .o (e.g., src/main.o src/freq.o).
- Why it does this (The Idiom): This is a "substitution reference," a classic make pattern for generating target file lists from source lists. It's concise and powerful.
- Your Takeaway: This is a very common and efficient way to define your object files.
TEST_SRCS and TEST_OBJS
- What it does: Exactly the same logic as above, but for the files in the tests directory.
- Why it does this (The Idiom): It cleanly separates the main application build from the test build.
- Your Takeaway: Keep your test sources and objects separate from your main application sources and objects.
CC ?= cc
- What it does: Conditionally sets the C compiler to cc (the system's default C compiler).
- Why it does this (The Idiom): This allows a user to easily specify a different compiler (e.g., make CC=clang).
- Your Takeaway: Always make the compiler configurable.
CFLAGS := -std=c11 -Wall -Wextra -I$(INC_DIR) -O2
- What it does: Defines the flags to pass to the compiler: use the C11 standard, enable all and extra warnings, look for headers in our include directory, and apply level-2 optimizations.
- Why it does this (The Idiom): It centralizes compiler options for consistency and quality control. -Wall -Wextra is a non-negotiable best practice for catching bugs.
- Your Takeaway: Centralize your compiler flags and always compile with warnings enabled.
LDLIBS :=
- What it does: Defines the libraries to link against. It's empty for this project.
- Why it does this (The Idiom): This is a placeholder. If your project needed the math library, you would set it to LDLIBS := -lm.
- Your Takeaway: Use LDLIBS to specify linker dependencies.

Part 2: Build Targets

This section defines what make can actually do. These are the commands you'll run, like make or make test.

# ---- build targets ---------------------------------------------------------
$(BIN): $(OBJS)
    $(CC) $^ -o $@ $(LDLIBS)

%.o: %.c
    $(CC) $(CFLAGS) -c $< -o $@

.PHONY: test test-bin install uninstall clean

test-bin: $(TEST_OBJS) $(OBJS)
    $(CC) $(TEST_OBJS) $(filter-out $(SRC_DIR)/main.o,$(OBJS)) -o $(TEST_DIR)/test_runner

test: test-bin
    $(TEST_DIR)/run.sh

install: $(BIN)
    install -Dm755 $(BIN) $(DESTDIR)$(PREFIX)/bin/$(BIN)

uninstall:
    rm -f $(DESTDIR)$(PREFIX)/bin/$(BIN)

clean:
    rm -f $(OBJS) $(TEST_OBJS) $(BIN) $(TEST_DIR)/test_runner

The Main Executable Rule: $(BIN): $(OBJS)
- What it does: This defines our main target. It states that the final executable (freq-counter) depends on all the object files (.o) listed in $(OBJS). The recipe below it links those object files together.
- Why it does this (The Idiom): It separates the final linking step from the intermediate compilation steps. The automatic variables $^ (all prerequisites) and $@ (the target) keep the rule generic and clean.
- Your Takeaway: Your primary build rule should depend on all object files and perform the final linking.
The Pattern Rule: %.o: %.c
- What it does: This is the powerful engine of our Makefile. It's a pattern that tells make: "To create any file that ends in .o, find the corresponding file that ends in .c and run this recipe."
- Why it does this (The Idiom): This single, generic rule handles the compilation for every .c file in our project. You never need to write another compilation rule. The -c flag tells the compiler to compile only and not link.
- Your Takeaway: This pattern rule is the standard, most efficient way to handle C compilation in a Makefile.
The Phony Targets: .PHONY: ...
- What it does: It declares that targets like clean, test, and install are "phony," meaning they don't produce an actual file with that name.
- Why it does this (The Idiom): This prevents conflicts if you ever had a file named test and improves performance slightly. It's a declaration of intent and a core best practice.
- Your Takeaway: Always declare non-file targets as .PHONY at the top of your targets section.
The Test Build Rule: test-bin: ...
- What it does: It builds a special test executable named test_runner.
- Why it does this (The Idiom): It links the test code with your application code, but with a crucial exception. The $(filter-out $(SRC_DIR)/main.o,$(OBJS)) function removes your application's main.o file from the list before linking. This is necessary because your test code has its own main() function, and you can't have two in one program.
- Your Takeaway: Use the filter-out pattern to exclude your main application's main.c when building a test runner.
The Test Run Rule: test: test-bin
- What it does: Defines an easy-to-use test target. It first ensures the test-bin executable is built and then runs an external shell script to perform the actual tests.
- Why it does this (The Idiom): It cleanly separates the concern of building the test executable from running the tests.
- Your Takeaway: A make test command should be simple for the user; hide the complexity in dependent targets and scripts.
The Install/Uninstall Rules: install: and uninstall:
- What it does: The install target copies the compiled program (freq-counter) into a system-wide directory (/usr/local/bin). The uninstall target removes it.
- Why it does this (The Idiom): It provides a standard way to make the tool available to all users on a system. Using the install command is better than cp because it can set permissions (-m755) and create parent directories (-D).
- Your Takeaway: If you provide an install target, always provide uninstall. Use the install command for professional-grade installations.
The Clean Rule: clean:
- What it does: Removes all files generated during the build process (all .o files and both executables).
- Why it does this (The Idiom): This allows you to guarantee a fresh build from a clean state, which is essential for debugging and release packaging.
- Your Takeaway: A clean target is a mandatory part of any serious Makefile.

Final Project Structure

After creating all the files, your project directory should look like this:

.
├── Makefile
├── include
│   └── freq.h
├── src
│   ├── freq.c
│   └── main.c
└── tests
    ├── run.sh
    └── test_freq.c

Full Code Listing

In this Github repository you can find the complete code for all the files so you can build and run this project yourself.
Bonus The project includes a CI/CD setup based on Github actions, which automatically handles the build, test and even release to a binary for further download.

Stop Saying "It Just Works." Save Your Credibility as a Senior and Say This Instead

medunes — Fri, 25 Jul 2025 14:58:02 +0000

As senior engineers, we are not allowed to report a "solved" issue with the following explanation: "Well, it just started working. I don't know how, but it's fixed for now."

Why? Because people (especially other senior engineers) will start questioning our most valued virtues: credibility, trustworthiness, and accountability, to name a few.

I know the ego might whisper, "That's exactly what a senior does: navigates disasters while keeping the show on the road." Well, that's not quite accurate. Let me tell you why.

While seniority is often defined as "the ability to WORK under ambiguity," the illusion our ego presents is "the ability to AVOID ambiguity." Notice the difference: "work under" versus "avoid."

A junior engineer is hired to "avoid" ambiguity. Once they get stuck, they are supposed to reach out to a senior colleague who knows how to "work under" ambiguity.

Too much philosophy, right? I promise I'm neither a TEDx speaker nor a Scrum evangelist. I'm a hands-on person.

To make things concise and to the point, here is a list of responses that senior engineers can use to maintain their credibility and prove they are capable of working under ambiguity:

1- "I performed a time-boxed debugging session for one hour. As it was a showstopper, I had to do a hard reset, and it's working now. I have documented the entire debugging process and can get back to it later."

2- "I have at least three theories as to why it suddenly started working again, but no way to prove any of them for now. I have an idea for a Proof of Concept (PoC) to validate them next sprint."

3- "Although there were no code changes or recent deployments, I will reach out to the operations team to check if they changed anything related to server resources."

4- "It started working again after a short outage. I will schedule a brief meeting to brainstorm with the relevant people about the situation."

5- "I would be lying if I told you the specific reason it started working again. I'll be honest with you: the context is very low-priority, as this is a local sandbox for a PoC. Therefore, I recommend that we simply ignore it for now."

6- "Even though it started working again 'by itself,' I consider this a showstopper that we should tackle ASAP. This area of the application is tightly bound to both integrity and security, and we cannot tolerate ignoring known threat vectors."

7- Finally, for the truly desperate, this is a professional, drop-in replacement for, "I have no clue; it just worked": "I could not find any sign of a change that might explain why it broke and then started working again. Let's attribute this single incident to a race condition, but if it happens again, we must perform a Root Cause Analysis (RCA)."

P.S. Needless to say, it doesn't help to just say these things. We have to be honest when we use them.

Clean Code = Change Insurance. Pay the Premium or Face Bankruptcy.

medunes — Sat, 12 Jul 2025 10:20:57 +0000

I have always been obsessed with understanding the deepest meanings and "metaphysics" of clean-code, or coding best practices in general. Then, I started to literally hate and reject most of what comes from that "movement", because some people and entities turned it into religions, hypes, brainwash, my way or the highway, ending up with it as a product to print on tee-shirts to wear in conferences.

Took a breath and stepped back and said: honestly, out of all that noise, are there facts I can convince my self with, as a pragmatic programmer, and argue with others based on them?

I ended up with the following seven "principles":

1- "ANY production code you write WILL have to change"

2- "Changing code costs way more than writing new code."

3- "Writing new code is not same as REWRITING old code to new code, the latter is also a type of code change"

4- "Clean Code is a set of empirically proven methods which reduce the cost of code change: the cleanest code is changeable with the lowest cost."

5- "Writing clean code costs more than writing dirty code. But modifying dirty code costs more than modifying clean code"

6- "There is no ONE RULE explaining when to write clean code: it is a matter of value for money decision."

7- "Clean code is not always optional: the cost of changing code can sometimes be infinite, under certain deadline restrictions. In this case a company can go bankrupt, or a government can be under permanent security threat."

ROUTE vs. INETNUM: What’s the Story?

medunes — Wed, 30 Apr 2025 11:50:59 +0000

The distinction between ROUTE and INETNUM objects is critical in understanding how CIDRs are managed and associated with ASNs. These are database objects used by RIRs to track IP address allocations and routing information.

INETNUM Object

Definition: An INETNUM (Internet Number) object represents an allocated or assigned range of IP addresses (a CIDR or IP range) managed by an RIR or delegated to an organization (e.g., ISP, end-user).
Purpose:
- Tracks the allocation or assignment of an IP address range.
- Records administrative details, such as the organization holding the IP range, contact information, and status (e.g., allocated, assigned).
- Indicates who owns or manages the IP range, not necessarily how it’s routed.
Scope: Primarily administrative. It’s about IP address ownership or stewardship, not routing.
Key Attributes (in RIPE, for example):
- inetnum: The IP range (e.g., 203.0.113.0 - 203.0.113.255 or 203.0.113.0/24).
- netname: A descriptive name for the network.
- status: Allocation status (e.g., ALLOCATED, ASSIGNED).
- org: The organization responsible for the range.
- admin-c/tech-c: Contact details.
ASN Association: An INETNUM object does not directly specify an ASN. It’s about allocation, not routing. However, the organization listed may also control an ASN, or the CIDR may be referenced in a ROUTE object for routing purposes.
Example:

  inetnum: 203.0.113.0 - 203.0.113.255  
  netname: EXAMPLE-NET  
  org: ORG-EX1-RIPE  
  status: ASSIGNED  
  admin-c: EX1-RIPE  
  tech-c: EX1-RIPE

ROUTE Object

Definition: A ROUTE object represents a CIDR (or IP range) that is announced in the global BGP routing table by a specific ASN.
Purpose:
- Tracks the routing of an IP prefix, specifying which ASN is responsible for announcing it to the internet.
- Helps ensure that only authorized ASNs announce a given CIDR, preventing route hijacking.
- Used by network operators to validate BGP announcements.
Scope: Routing-focused. It’s about how the CIDR is advertised on the internet.
Key Attributes (in RIPE, for example):
- route: The CIDR being announced (e.g., 203.0.113.0/24).
- origin: The ASN announcing the route (e.g., AS12345).
- descr: Description of the route.
- mnt-by: Maintainer responsible for the object.
ASN Association: The ROUTE object directly specifies the ASN via the origin attribute, explicitly linking the CIDR to the autonomous system announcing it.
Example:

  route: 203.0.113.0/24  
  origin: AS12345  
  descr: Example Network Route  
  mnt-by: EXAMPLE-MNT

Key Differences Between INETNUM and ROUTE

Aspect	INETNUM	ROUTE
Purpose	Tracks IP address allocation/assignment.	Tracks BGP routing of an IP prefix.
Scope	Administrative (ownership/management).	Operational (routing/announcement).
ASN Association	No direct ASN link; tied to an organization.	Directly specifies ASN via `origin`.
Content	IP range, org, contacts, status.	CIDR, ASN, routing details.
Use Case	Who owns or manages the IP range?	Which ASN announces the IP range?
Example	`203.0.113.0/24` assigned to an organization.	`203.0.113.0/24` announced by `AS12345`.

Relationship Between INETNUM and ROUTE

Complementary Roles:
- An INETNUM object defines the allocation of a CIDR (who it’s assigned to).
- A ROUTE object defines how that CIDR is routed (which ASN announces it).
Overlap:
- A CIDR in an INETNUM object may have a corresponding ROUTE object if it’s publicly routable. For example, 203.0.113.0/24 might be allocated to an ISP in an INETNUM and announced by that ISP’s ASN in a ROUTE object.
- Not all INETNUM CIDRs have ROUTE objects. For example, private IPs or non-routed allocations (e.g., for internal use) won’t have ROUTE objects.
Sub-Allocations:
- An INETNUM might cover a large block (e.g., 203.0.112.0/20), which is sub-allocated into smaller CIDRs (e.g., 203.0.113.0/24). Each sub-CIDR might have its own ROUTE object, potentially announced by different ASNs (e.g., if sub-allocated to different organizations).
Validation:
- Network operators use ROUTE objects to validate BGP announcements.

Got more questions about the topic? Drop a comment below!

From PHPUnit to Go: Data-Driven Unit Testing for Go Developers

medunes — Sun, 10 Nov 2024 21:48:36 +0000

In this post, we'll explore how to bring the PHP unit testing mindset, particularly the PHPUnit framework's data provider approach, into Go. If you're an experienced PHP developer, you’re likely familiar with the data provider model: gathering test data separately in raw arrays and feeding this data into a test function. This approach makes unit tests cleaner, more maintainable, and adheres to principles like Open/Closed.

Why the data provider Approach?

Using a data provider approach to structure unit tests in Go provides several advantages, including:

Enhanced Readability and Extensibility: Tests become visually organized, with clearly separated arrays at the top representing each test scenario. Each array's key describes the scenario, while its content holds the data to test that scenario. This structure makes the file pleasant to work on and easy to extend.

Separation of Concerns: The data provider model keeps data and test logic apart, resulting in a lightweight, decoupled function that can remain largely unchanged over time. Adding a new scenario only requires appending more data to the provider, keeping the test function open for extensions but closed for modification—a practical application of the Open/Closed Principle in testing.

In some projects, I’ve even seen scenarios dense enough to warrant using a separate JSON file as the data source, manually built and fed to the provider, which in turn supplies data to the test function.

When it is very encouraged to use data providers?

Using data providers is especially encouraged when you have a large number of test cases with varying data: each test case is conceptually similar but differs only in input and expected output.

Intermingling data and logic in a single test function can reduce Developer Experience (DX). It often leads to:

Verbosity Overload: Redundant code that repeats statements with slight data variations, leading to a codebase that is verbose without added benefit.

Reduced Clarity: Scanning through the test function becomes a chore when trying to isolate the actual test data from the surrounding code, which the data provider approach naturally alleviates.

Nice, so what is exactly a data provider?

The DataProvider pattern in PHPUnit where basically the provider function supplies the test function with different sets of data that gets consumed in an implicit loop. It ensures the DRY (Don't Repeat Yourself) principle, and aligns with the Open/Closed Principle as well,by making it easier to add or modify test scenarios without altering the core test function logic.

Solving the problem without a data provider?

To illustrate the drawbacks of verbosity, code duplication, and maintenance challenges, here is a snippet of an example of unit test for the bubble sort function without the help of data providers:

<?php

declare(strict_types=1);

use PHPUnit\Framework\TestCase;

final class BubbleSortTest extends TestCase
{
    public function testBubbleSortEmptyArray()
    {
        $this->assertSame([], BubbleSort([]));
    }

    public function testBubbleSortOneElement()
    {
        $this->assertSame([0], BubbleSort([0]));
    }

    public function testBubbleSortTwoElementsSorted()
    {
        $this->assertSame([5, 144], BubbleSort([5, 144]));
    }

    public function testBubbleSortTwoElementsUnsorted()
    {
        $this->assertSame([-7, 10], BubbleSort([10, -7]));
    }

    public function testBubbleSortMultipleElements()
    {
        $this->assertSame([1, 2, 3, 4], BubbleSort([1, 3, 4, 2]));
    }

    // And so on for each test case, could be 30 cases for example.

    public function testBubbleSortDescendingOrder()
    {
        $this->assertSame([1, 2, 3, 4, 5], BubbleSort([5, 4, 3, 2, 1]));
    }

    public function testBubbleSortBoundaryValues()
    {
        $this->assertSame([-2147483647, 2147483648], BubbleSort([2147483648, -2147483647]));
    }
}

Are there issues with the above code? sure:

Verbosity: Each test case requires a separate method, resulting in a large, repetitive code-base.

Duplication: Test logic is repeated in each method, only varying by input and expected output.

Open/Closed Violation: Adding new test cases requires altering the test class structure by creating more methods.

Solving the problem with data provider!

Here’s the same test suite refactored to use a data provider

<?php

declare(strict_types=1);

use PHPUnit\Framework\TestCase;

final class BubbleSortTest extends TestCase
{
    /**
     * Provides test data for bubble sort algorithm.
     *
     * @return array<string, array>
     */
    public function bubbleSortDataProvider(): array
    {
        return [
            'empty' => [[], []],
            'oneElement' => [[0], [0]],
            'twoElementsSorted' => [[5, 144], [5, 144]],
            'twoElementsUnsorted' => [[10, -7], [-7, 10]],
            'moreThanOneElement' => [[1, 3, 4, 2], [1, 2, 3, 4]],
            'moreThanOneElementWithRepetition' => [[1, 4, 4, 2], [1, 2, 4, 4]],
            'moreThanOneElement2' => [[7, 7, 1, 0, 99, -5, 10], [-5, 0, 1, 7, 7, 10, 99]],
            'sameElement' => [[1, 1, 1, 1], [1, 1, 1, 1]],
            'negativeNumbers' => [[-5, -2, -10, -1, -3], [-10, -5, -3, -2, -1]],
            'descendingOrder' => [[5, 4, 3, 2, 1], [1, 2, 3, 4, 5]],
            'randomOrder' => [[9, 2, 7, 4, 1, 6, 3, 8, 5], [1, 2, 3, 4, 5, 6, 7, 8, 9]],
            'duplicateElements' => [[2, 2, 1, 1, 3, 3, 4, 4], [1, 1, 2, 2, 3, 3, 4, 4]],
            'largeArray' => [[-1, -10000, -12345, -2032, -23, 0, 0, 0, 0, 10, 10000, 1024, 1024354, 155, 174, 1955, 2, 255, 3, 322, 4741, 96524], [-1, -10000, -12345, -2032, -23, 0, 0, 0, 0, 10, 10000, 1024, 1024354, 155, 174, 1955, 2, 255, 3, 322, 4741, 96524]],
            'singleNegativeElement' => [[-7], [-7]],
            'arrayWithZeroes' => [[0, -2, 0, 3, 0], [-2, 0, 0, 0, 3]],
            'ascendingOrder' => [[1, 2, 3, 4, 5], [1, 2, 3, 4, 5]],
            'descendingOrderWithDuplicates' => [[5, 5, 4, 3, 3, 2, 1], [1, 2, 3, 3, 4, 5, 5]],
            'boundaryValues' => [[2147483648, -2147483647], [-2147483647, 2147483648]],
            'mixedSignNumbers' => [[-1, 0, 1, -2, 2], [-2, -1, 0, 1, 2]],
        ];
    }

    /**
     * @dataProvider bubbleSortDataProvider
     *
     * @param array<int> $input
     * @param array<int> $expected
     */
    public function testBubbleSort(array $input, array $expected)
    {
        $this->assertSame($expected, BubbleSort($input));
    }
}

Are there any advantages of using the data provider? oh yeah:

Conciseness: All test data is centralized in a single method, removing the need for multiple functions for each scenario.

Enhanced Readability: Each test case is well-organized, with descriptive keys for each scenario.

Open/Closed Principle: New cases can be added to the data provider without altering the core test logic.

Improved DX (Developer Experience): Test structure is clean, appealing to the eyes, making even those lazy developers motivated to extend, debug, or update it.

Bringing Data Providers to Go

Go doesn't have a native data provider model like PHPUnit, so we need to use a different approach. There could be many implementation with several levels complexity, the following is an average one that might be a candidate to simulate data provider in Go land

package sort

import (
    "testing"

    "github.com/stretchr/testify/assert"
)

type TestData struct {
    ArrayList    map[string][]int
    ExpectedList map[string][]int
}

const (
    maxInt32 = int32(^uint32(0) >> 1)
    minInt32 = -maxInt32 - 1
)

var testData = &TestData{
    ArrayList: map[string][]int{
        "empty":                            {},
        "oneElement":                       {0},
        "twoElementsSorted":                {5, 144},
        "twoElementsUnsorted":              {10, -7},
        "moreThanOneElement":               {1, 3, 4, 2},
        "moreThanOneElementWithRepetition": {1, 4, 4, 2},
        "moreThanOneElement2":              {7, 7, 1, 0, 99, -5, 10},
        "sameElement":                      {1, 1, 1, 1},
        "negativeNumbers":                  {-5, -2, -10, -1, -3},
        "descendingOrder":                  {5, 4, 3, 2, 1},
        "randomOrder":                      {9, 2, 7, 4, 1, 6, 3, 8, 5},
        "duplicateElements":                {2, 2, 1, 1, 3, 3, 4, 4},
        "largeArray":                       {-1, -10000, -12345, -2032, -23, 0, 0, 0, 0, 10, 10000, 1024, 1024354, 155, 174, 1955, 2, 255, 3, 322, 4741, 96524},
        "singleNegativeElement":            {-7},
        "arrayWithZeroes":                  {0, -2, 0, 3, 0},
        "ascendingOrder":                   {1, 2, 3, 4, 5},
        "descendingOrderWithDuplicates":    {5, 5, 4, 3, 3, 2, 1},
        "boundaryValues":                   {2147483648, -2147483647},
        "mixedSignNumbers":                 {-1, 0, 1, -2, 2},
    },
    ExpectedList: map[string][]int{
        "empty":                            {},
        "oneElement":                       {0},
        "twoElementsSorted":                {5, 144},
        "twoElementsUnsorted":              {-7, 10},
        "moreThanOneElement":               {1, 2, 3, 4},
        "moreThanOneElementWithRepetition": {1, 2, 4, 4},
        "moreThanOneElement2":              {-5, 0, 1, 7, 7, 10, 99},
        "sameElement":                      {1, 1, 1, 1},
        "negativeNumbers":                  {-10, -5, -3, -2, -1},
        "descendingOrder":                  {1, 2, 3, 4, 5},
        "randomOrder":                      {1, 2, 3, 4, 5, 6, 7, 8, 9},
        "duplicateElements":                {1, 1, 2, 2, 3, 3, 4, 4},
        "largeArray":                       {-1, -10000, -12345, -2032, -23, 0, 0, 0, 0, 10, 10000, 1024, 1024354, 155, 174, 1955, 2, 255, 3, 322, 4741, 96524},
        "singleNegativeElement":            {-7},
        "arrayWithZeroes":                  {-2, 0, 0, 0, 3},
        "ascendingOrder":                   {1, 2, 3, 4, 5},
        "descendingOrderWithDuplicates":    {1, 2, 3, 3, 4, 5, 5},
        "boundaryValues":                   {-2147483647, 2147483648},
        "mixedSignNumbers":                 {-2, -1, 0, 1, 2},
    },
}

func TestBubble(t *testing.T) {

    for testCase, array := range testData.ArrayList {
        t.Run(testCase, func(t *testing.T) {
            actual := Bubble(array)
            assert.ElementsMatch(t, actual, testData.ExpectedList[testCase])
        })

    }
}

We basically define two maps/lists: one for the input data and the second for the expected data. We ensure that each case scenario on both sides is referred through the same map key on both sides.
Executing the tests is then a matter of a loop in a simple function that iterates over the prepared input/expected lists.
Except some one-time boiler-plate of types, modifications to tests should only happen on the data side, mostly no change should alter the logic of the function executing tests, thus achieving the goals we've talked about above: reducing test work down to a matter of raw data preparation.

Bonus: A Github repository implementing the logic presented in this blogpost can be found here https://github.com/MedUnes/dsa-go. So far it contains Github actions running these tests and even showing that super famous green badge ;)

See you in the next [hopefully] informative post!

Combining 2FA and Public Key Authentication for a better Linux SSH security

medunes — Wed, 06 Dec 2023 10:36:47 +0000

What are we trying to improve?

SSH (Secure Shell Connection) is a secure way to login to a Linux server and remotely work with it. However there might be a good margin of further improvements to secure even more this.

1- Substitute password authentication with public key authentication:

Security: Public key authentication is more secure than passwords. Passwords can be brute-forced or guessed, while a cryptographic key pair (public and private keys) is practically impossible to crack with current technology.
No Replay Attacks: Since the private key is never transmitted over the network, there's no risk of interception and replay attacks, unlike passwords.
Automation: Public keys are great for automated processes. You can use SSH without entering a password each time, which is essential for scripts and system administration tasks.
Management: It's easier to manage and revoke access with public keys. Instead of changing a password (which might be shared or used on multiple systems), you just remove the public key from the server.
Phishing Resistant: Users are less susceptible to phishing attacks since they're not entering a password that could be captured.

2- Disable root login from the SSH configuration:

Mitigate Brute Force Attacks: Root is a known username and often targeted by brute force attacks. Disabling root login means attackers can't directly access the most privileged account.
Limit Privilege Escalation: Even if an attacker compromises a regular user account, they still need to find a way to escalate privileges to root, adding an extra layer of security.
Audit Trails: Using sudo from a regular account to perform administrative tasks leaves a trail, helping in auditing and monitoring activities.
Reduced Risk of Accidental Damage: Preventing direct root access reduces the risk of accidental high-impact changes by system administrators.
Compliance: Many security standards and best practices advise against using root accounts for routine administration.

3- Force 2FA authentication with TOTP: Adding Time-based One-Time Password (TOTP) as an additional layer to SSH authentication significantly boosts security:

Two-Factor Authentication: TOTP introduces a second factor of authentication. Even if an attacker steals a user's SSH key or password, they still need the TOTP, which is typically generated on a device the user possesses.
Dynamic Codes: TOTPs change every 30-60 seconds. This makes stolen codes useless after a very short time, countering replay attacks.
Mitigates Phishing: TOTPs are harder to phish than static passwords because they are constantly changing and are only valid for a short period.
No Network Dependency: TOTPs are generated by an algorithm based on time and a secret key, so they don't require network connectivity, making them reliable and efficient.
Harder to Intercept: Unlike static passwords, intercepting a TOTP doesn't compromise future logins, as each password is valid for only one login session.

4- Change SSH server port from default 22 to a less common port number

Reduce Automated Attacks: Many bots and scripts target port 22 for SSH attacks. Changing the port can reduce the volume of these automated attacks.
Lower Profile: By not using the default port, your server becomes less obvious to casual scanners who are looking for easy targets.
Filter Out Noise: Changing the port can reduce log noise from repeated login attempts, making it easier to spot genuine security threats.

Configuring your local machine

1- Setup Public Key Authentication:

Generate Key Pair:
To make the public key authentication work, we need to generate the called "key-pair": the public key which you share with the remote server, and the private key which must be kept private and secure on your local machine.
For enhancing even more security, you can add a passphrase to your private key so that is won't be possible to use it until the passphrase is entered.
Fortunately some commonly used tools you can achieve all the burden above with the simple commands below:

# replace my_server_name here eventually
# when prompted with passphrase, enter it with keyboard
ssh-keygen -t ed25519 -f ~/.ssh/my_server_name

# replace my_server_name here eventually
ssh-copy-id -i ~/.ssh/my_server_name.pub user@remote_host

If ssh-copy-id is not an option, you still can manually copy the public key to the remote server. Follow the steos below only if ssh-copy-id doesn't work for you:
First display and copy your public key: (should be available after the generation steps above)

cat ~/.ssh/my_server_name.pub

Then open the authorized_keys file on the remote server and paste the copied key to its end.

nano ~/.ssh/authorized_keys

Now an important step, do not forget to apply necessary permissions

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

2- Add SSH configuration (optional):

This will improve the UX while logging into your remote server making it more convenient.
For this we suppose that your remote host IP is 192.168.12.34 and we will suppose the SSH port has been set on the remote server to, for example, 4898.
Based on these parameters, you should add this section to your ~/.ssh/config file.

#~/.ssh/config
Host my_server_name
    HostName 192.168.12.34
    User my_username
    IdentityFile /home/my_username/.ssh/my_server_name
    Port 4898

3- Have a TOTP client:

You will need this to be able to generate the TOTP number once prompted from the remote server.
You have couple options here: Mobile apps like Google Authenticator or Authy, Desktop applications like Keepass TOTP or even more advanced tools like YubiKey

Configuring your remote server

Instructions here are tested on Debian based Linux distributions, but should work on other distros as well without "big" differences.

1- Install google authenticator:

Here you run the authenticator installation then you execute it, and we will answer "y" for all the prompts.

Installation:

sudo apt install libpam-google-authenticator
...
...
...

Execution:

google-authenticator
Do you want authentication tokens to be time-based (y/n) y
█████████████████████████
██ ▄▄▄▄▄ █▀▄█▄█ █ ▄▄▄▄▄ ██
██ █   █ █▀▄▀█▄█ █   █ ██
██ █▄▄▄█ █ ▀ ▀ ▄ █▄▄▄█ ██
██▄▄▄▄▄▄▄█▄█ ▀ █▄▄▄▄▄▄▄██
██▄▀▄▀▄█ ▀▄█▀▄█▄█▀█▀██▀██
██▄█▄██▄▀▄▄▀█▄▀ ▀▄█▄▀▀▄██
██▄▄▄▄▄▄▄█▄▄█▄▄███▄█▄▄▄███
█████████████████████████

Your new secret key is: 4D3FPZ2W6Y7IOMV 
Your verification code is 123456
Your emergency scratch codes are:
81234567
89123456
78123456
69123456
58123456

Pay attention to the generated codes: Use The ASCII made QR code (yay, terminal!) to add the TOTP to your smartphone app by adding new entry and scanning the picture, and use the secret key to add a TOTP setup to your keepass application and/or YubiKey. The backup codes should be saved for eventual emergency cases.

2- Configure SSH server:

Here we will act on two configs: the SSHD and the PAM. As we explained in the first section, we will edit the SSH daemon config file to disable password authentication and root user, keep interactive keyboard for TOTP prompting, enable the Public Key authentication and change the SSH port number.
The resulting config file /etc/ssh/sshd_config should look like this:

sudo nano /etc/ssh/sshd_config

# This one we changed from default Port 22
Port 4898

# Add this entry or edit it if it is already existing
PermitRootLogin no

# We can explicitly set this although it should be the default value even if omitted. 
PubkeyAuthentication yes

# This setting will disable the password based authentication. 
PasswordAuthentication no

# This entry will allow both publickey authentication and keyboard-interactive which # we need to enter our TOTP code
AuthenticationMethods publickey,keyboard-interactive

# PAM (Pluggable Authentication Modules) is also required to allow google 
# authenticator #integration
UsePAM yes

# Depending on your Debian version, if you find the entry 
# KbdInteractiveAuthentication existing in the config file, then use it, otherwise you 
# might find the deprecated entry which is ChallengeResponseAuthentication which
# in that case should be set to yes instead.
KbdInteractiveAuthentication yes

3- Configure PAM: for this we need to enter some changes to the /etc/pam.d/sshd file:

sudo nano /etc/pam.d/sshd

First, find the following three lines and comment them out

#@include common-auth
# account  required     pam_access.so
#@include common-password

Then add the following line to the end of the file:

# two-factor authentication via Google Authenticator
auth required pam_google_authenticator.so

Now we only have one last step to go: reststart the SSH server

 sudo systemctl restart sshd

Server setup should be complete ;)

SSH like a boss

Given all the steps above correctly achieved, you should by now be able to ssh to your remote server as easy as the following:

 ssh my_server_name
(my_username@192.168.12.34) Verification code: 
Linux raspberrypi 6.1.0-rpi6-rpi-v8 #1 SMP PREEMPT Debian 1:6.1.58-1+rpt2 (2023-10-27) aarch64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: Wed Dec  6 01:16:51 2023 from 192.168.12.33
my_username@my_server_name:~ $

You will be of course prompted for the TOTP code (4 digits) which you should use your smartphone, keepass or YubiKey to get them.

So that was pretty match it. I will be happy to support for any further questions, rectifications or simple likes :)

How to log your life easier in Symfony?

medunes — Tue, 01 Mar 2022 22:26:33 +0000

Hi coderz, how you doing? I know you are fed-up with blogposts and have tons of work, yet, check this!

The goal:

Turning any class in your project "logging-able", yet with the least possible changes and boilerplate verbosity.

The classical way:

So knowing that monolog's logger (however you configure it) is a tagged service at the end, the "only" way to "cleanly" use it is to DI/inject it to the needed service
Injecting services in Symfony can be done with multiple approaches and strategies. But in best cases you'll have at least to touch two things:
- The class needing the logger by defining a private property to receive the logger service instance, and an assignement in the constructor to actually receive the service.
- The services.yaml if you choose to go with setter injection rather than constructor injection (as the latter can benefit from autowiring)
Now as logging is a "nice and wanted" feature, your urge to log stuff here and there can grow over and over, and you might feel silly polluting your code with one more line of properties and one other in the constructor. Sometimes you'd only write a constructor for the sake eyes of the DI injection of the logger. Having this exact snippet copy/pasted over a dozen of classes might really make you feel unhappy.

The shortcut:

If you use the autocomplete feature of PHPStorm, you'd notice a pair of interface/trait having the same prefix.
- Psr\Log\LoggerAwareInterface
- Psr\Log\LoggerAwareTrait
Can we use them altogether to solve the issue above? → yes.
In general the SomethingAwareInterface naming pattern, means the class is supposed to have a method named "setSomething()".
And following conventions as well, having that setter means your class should have a "something" property that setter will modify, and here comes the SomethingAwareTrait to define that property for you.
Now implementing/using that interface/trait makes your class having a property named "something" and a setter for it. Nice thing here is that all that code verbosity is totally hidden in the backyard.
Still one single obstacle: How will the trait actually get the service instance.
One solution we might think about is the "@required" annotation above the setLogger() method, but in our case the setter is defined in the used trait, and we can't modify it.

A once and for all solution is to slightly modify the application's kernel, so that it loops over all services before the container is built, and check if any service is a "somethingAware", then make him really aware of it by explicitly injecting the service. Here is a showcase to make any class of your project that implement/use the pair above, being able to use the logger straight away without any further overhead:

<?php

// src/Kernel.php

namespace App;

use DateTime;
use Psr\Log\LoggerAwareInterface;
use Symfony\Bundle\FrameworkBundle\Kernel\MicroKernelTrait;
use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\Definition;
use Symfony\Component\HttpKernel\Kernel as BaseKernel;

class Kernel extends BaseKernel implements CompilerPassInterface
{
    use MicroKernelTrait;

    public function process(ContainerBuilder $container): void
    {
        $definitions = $container->getDefinitions();
        foreach ($definitions as $definition) {
            if (!$this->isAware($definition, LoggerAwareInterface::class)) {
                continue;
            }
            $definition->addMethodCall(
                 'setLogger',
                [$container->getDefinition('monolog.logger')]
             );
        }
    }

 private function isAware(Definition $definition, string $awarenessClass): bool
 {
     $serviceClass = $definition->getClass();
     if ($serviceClass === null) {
         return false;
     }
     $implementedClasses = @class_implements($serviceClass, false);
     if (empty($implementedClasses)) {
         return false;
     }
     if (\array_key_exists($awarenessClass, $implementedClasses)) {
         return true;
     }

     return false;
 }

}

Now Just use implement the interface and use the trait in your command, for example, and you are ready to go!

<?php

// src/Command/MyCommand.php

declare(strict_types=1);

namespace App\Command;

use Psr\Log\LoggerAwareInterface;
use Psr\Log\LoggerAwareTrait;
use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;

#[AsCommand(
    name: 'app:my-command',
    description: 'test!',
)]
class MyCommand extends Command implements LoggerAwareInterface
{
    use LoggerAwareTrait;

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $this->logger->info('I can log!');

        return Command::SUCCESS;
    }
}

You can clone/download the code snippets above from this gist on github as well

Enough talk for today, hope it helped and see you soon!

How to make two docker containers from two different projects communicate with each others ?

medunes — Mon, 07 Feb 2022 23:37:41 +0000

The problem:

You have a container under a docker-compose project, that you want to communicate or access another container which exists under a second docker-compose project

A real-life situation?

For some security policy, your SysOp or hosting provider blocks all external traffic, except those for port 80 (HTTP) or port 443 (HTTPS). However, you want to set up and manage several web (or non-web) services on your machine, basically using docker containers and managed by docker-compose.
To handle this you set-up a reverse-proxy using a dedicated docker-compose project and container, called proxy.
The proxy container/project listens on port 80, for all incoming external requests. (The nginx config can distinguish the called domain with the server_name directive)
On the other side, on another docker-compose project, you have a Kibana service that serves request on kibana.exemple.com, but under port 5601 (still HTTP traffic).
The Kibana service is on a dedicated container called kibana, among three other containers in the ELK docker-compose porject (different from the reverse-proxy project).
The solution as you would guess, is that the reverse-proxy forwards the external http://kibana.exemple.com:80 to an internal http://kibana:5601, to solve the port restriction issue.
The kibana domain name used when we want to hit the http://kibana:5601 endpoint, is actually unknown to the outside, or even to the host machine (in principle), it is only internally resolvable by docker built-in DNS to map it to the kibana container.
The problem here is, the network to which the kibana container belongs to is internal and only visible within the ELK docker compose projcet, to which kibana container belongs.
Yet, we want the reverse-proxy container that lives in a separated project to be able to hit that endpoint without much boilerplate work.

A solution?

Fortunately, docker-compose provides an easy way to solve this kind of situations, which is the external networks.
An external network must be defined, outside from the docker-compose config (one way through a docker-compose command)
Both networks should join this network, and, that's all.
Now you can just refer the container by its name from one or the other side as if they were on the same project
Here it how the official docker-compose defines the feature:

How to make it work?

Create an external network from command line, here we suppose you name it proxy_external

$ docker network create proxy_external

Add the proxy_external under the services → proxy→ networks level of docker-compose.yml of the reverse-proxy project
Add the proxy_external straight under the networks level of docker-compose.yml of the elk project . Define this as an external network

# reverse-proxy project

version: "3.8"
services:
  proxy:
    # ..
    networks:

      # This is the internal network for the reverse-proxy project
      - proxy

      # This is the external proxy
      - proxy_external
networks:

  # This is the server's network, defined by the service
  proxy: ~

  # This is an external network. It serves as a bridge between reverse-proxy and other projects.
  proxy_external:
    external:
      name: proxy_external

Add the proxy_external under the services → kibana→ networks level of docker-compose.yml of the reverse-proxy project
Add the proxy_external straight under the networks level of docker-compose.yml of the elk project . Define this as an external network

# elk project

version: "3.8"
services:
  elk
    # ..
    networks:

      # This is the internal network for the elk project
      - elk

      # This is the external proxy
      - proxy_external
networks:

  # This is the server's network, defined by the service
  elk: ~

  # This is an external network. It serves as a bridge between reverse-proxy and other projects.
  proxy_external:
    external:
      name: proxy_external

DEV Community: medunes

Your Connection is Not Private: What Your Browser Is Warning You About?

Level 1: The "Handwritten ID" Problem (Self-Signed vs. CA)

Level 2: The Anatomy of Trust (How "Belief" Works)

Level 3: The Intermediate Gap (Why R3?)

Level 4: The "Blast Radius" (Risk Management)

Level 5: The Loophole (Revocation & The "Bricked" vs. "Vulnerable" Trade-off)

Summary

Further Reading (References)

We don't do that here: How to Go the Go way - Part 1

How they do it the Go way?

The Alternatives: Why not New(a, b, c) or New(Config)?

1. The "Massive Constructor" Problem

2. The New(Config) Problem

The Java/OOP Equivalent (The Builder Pattern)

The PHP/Symfony Equivalent (Options Resolver)

Summary

Demystifying Go Mutex: How Synchronization Works Under the Hood

The Code We'll Analyze

Busting a Common Myth: It's Not Memory Protection

The Real Magic: A Two-Phase Strategy

Phase 1: The Fast Path (Atomic Optimism)

Phase 2: The Slow Path (A Little Nap)

Visualizing the Goroutine Dance

A Step-by-Step Walkthrough

A Simple Analogy: The Single Bathroom Key

Conclusion

Further Reading

Creating a REST API in Go with Gin: A Pragmatic, Spec-First Guide

The Problem: Specification Hell or Heaven?

The Plan: Spec -> Generate -> Implement

Project Structure: Go Standard Layout

Step 1: Define the API with OpenAPI 3

Step 2: Automate Code Generation with a Makefile

Step 3: Implement the Business Logic

Step 4: Wire It All Together

Conclusion: A Maintainable, Scalable Foundation

References

Build C Projects Like a Pro: A Guide to Idiomatic Makefiles

The Project: A Simple Frequency Counter

The Makefile: An Overview

Let's dive in.

The Makefile Breakdown

Part 1: Configuration

Part 2: Build Targets

Final Project Structure

Full Code Listing

Stop Saying "It Just Works." Save Your Credibility as a Senior and Say This Instead

Clean Code = Change Insurance. Pay the Premium or Face Bankruptcy.

ROUTE vs. INETNUM: What’s the Story?

INETNUM Object

ROUTE Object

Key Differences Between INETNUM and ROUTE

Relationship Between INETNUM and ROUTE

From PHPUnit to Go: Data-Driven Unit Testing for Go Developers

Why the data provider Approach?

When it is very encouraged to use data providers?

Nice, so what is exactly a data provider?

Solving the problem without a data provider?

Solving the problem with data provider!

Bringing Data Providers to Go

Combining 2FA and Public Key Authentication for a better Linux SSH security

What are we trying to improve?

Configuring your local machine

Configuring your remote server

SSH like a boss

How to log your life easier in Symfony?

The goal:

The classical way:

The shortcut:

How to make two docker containers from two different projects communicate with each others ?

The problem:

A real-life situation?

A solution?

How to make it work?

Further readings:

The Alternatives: Why not `New(a, b, c)` or `New(Config)`?

2. The `New(Config)` Problem

Step 2: Automate Code Generation with a `Makefile`