Coder Legion - Recent posts tagged golang

A Weekend Project With Docker Agent: Four Agents, Two Config Files, One Permissions Trap

Tue, 13 Oct 2026 13:02:21 +0000

Docker Agent lets me describe a team of AI agents, their tools, and their guardrails in one config file that a platform team can review like any other piece of infrastructure. That is the part I like most. It also has a permissions trap that I reproduced in a test, and I'll show it before you copy any example rules.

I spent a weekend-sized block of time building a small project to find out how far that idea goes. The result is release-gate-crew: four agents that review a service's container and CI configuration before release and write a PASS/BLOCK report.

What Docker Agent is

Docker Agent is Docker's open-source runtime for teams of agents. You write a config, run docker agent run crew.yaml, and talk to the root agent, which delegates to the sub-agents you declared. It ships in Docker Desktop 4.63 and later (versions 4.49 to 4.62 called it cagent), or as a standalone binary from GitHub releases. It works with Anthropic, OpenAI, Google, Bedrock, Docker Model Runner and a long list of other providers.

I used v1.150.0, released 9 October 2026.

The team

              root (lead)                think, todo
             /     |      \
 container_auditor  pipeline_auditor  scribe
 fs: ./target       fs: ./target      fs: ./reports
 shell: grep -n

The lead never reads files. It delegates, then makes the gate call: BLOCK if any finding is high or critical.
The container auditor reads target/Dockerfile and target/compose.yaml, and may run grep -n.
The pipeline auditor reads the CI workflow in target/ci/.
The scribe writes reports/gate-report.md and can write nowhere else.

target/ is a deliberately bad sample service: FROM node:latest, a token baked into ENV, a privileged container with the Docker socket mounted, and a pull_request_target workflow that checks out pull request code with permissions: write-all.

The whole team is one file

Here is the core of crew.yaml:

models:
  lead:   { provider: anthropic, model: claude-sonnet-4-5, max_tokens: 8000 }
  worker: { provider: anthropic, model: claude-haiku-4-5,  max_tokens: 4000 }

agents:
  root:
    model: lead
    description: Release gate lead. Delegates reviews and makes the PASS/BLOCK call.
    instruction_file: prompts/lead.md
    sub_agents: [container_auditor, pipeline_auditor, scribe]
    toolsets:
      - type: think
      - type: todo

  container_auditor:
    model: worker
    description: Reviews Dockerfile and compose files for container risks.
    instruction_file: prompts/container_auditor.md
    toolsets:
      - type: filesystem
        allow_list: ["./target"]
      - type: shell

  # pipeline_auditor and scribe follow the same shape

The sub_agents line is the whole orchestration. The runtime gives the lead a transfer_task tool and handles the hand-off. Each agent can use a different model, so the coordinator gets the stronger one and the workers get the cheaper one.

This is why I prefer config to framework code for this kind of work. In a code-first framework, the same team is classes, a tool registry, a loop, and retry handling, and the permissions live wherever someone remembered to put them. Here the reviewer sees the topology, the tool scope, and the policy in one diff. Swapping a provider is a two-line change. Nothing about the agents is hidden in a helper function.

The same team in HCL

Docker Agent also reads HCL. If your team writes Terraform, this will feel familiar:

agent "container_auditor" {
  model       = "worker"
  description = "Reviews Dockerfile and compose files for container risks."
  instruction = file("prompts/container_auditor.md")

  toolset "filesystem" {
    allow_list = ["./target"]
  }
  toolset "shell" {}
}

permissions {
  allow = ["read_file", "read_multiple_files", "shell:cmd=grep -n *"]
  deny  = ["shell:cmd=*curl*", "shell:cmd=*&&*", "shell:cmd=*;*", "shell:cmd=*|*"]
}

The runtime converts HCL to the YAML shape and validates both against the same schema. Labelled blocks and heredocs suit long prompts and per-agent commands well. Keep your expectations modest, though: there are no variables, locals or modules, and file() is the only function. It is a second syntax, not a second language. I keep both files in the repo and run the same tests against each, so they cannot drift apart silently.

Guardrails live next to the agents

This is where Docker Agent reads like a DevOps tool rather than an AI demo. Every layer is declared in the same file:

Layer	Config	Effect
Filesystem scope	`allow_list` per toolset	Auditors read only `./target`. The scribe writes only `./reports`.
Hidden files	`.agentsignore`	`.env`, keys and certs disappear from listings, reads and writes.
Tool rules	`permissions`	Deny, then allow, then ask.
Safety mode	`runtime.safety: restricted`	Unattended runs deny anything not explicitly allowed, without prompting.
Spend	`budget`	One shared $0.50 and 10-minute ceiling for all four agents.
Isolation	`--sandbox`	Runs the team in a Docker Sandboxes VM.

The budget detail is thoughtful. A named budget is one shared pot, so a lead that fans out to ten sub-agents cannot spend ten times the cap.

Two other features earned their place. Flavors are named patches inside the config, so --flavor cheap swaps the lead to a smaller model without a second file. Sharing packages the config as an OCI artifact: docker agent share push ./crew.yaml you/release-gate-crew, then anyone with access can docker agent run you/release-gate-crew.

Testing the guardrails without an API key

A config file is only as trustworthy as the tests behind it, so I wanted CI to prove the guardrails hold on every push without paying for tokens.

I wrote a small OpenAI-compatible stub model in Go, standard library only. It plays a fixed script per agent: the lead delegates three times, the auditors read files, and then they deliberately try things they shouldn't. An offline flavor points every agent at the stub:

flavors:
  offline:
    providers:
      stub:
        api_type: openai_chatcompletions
        base_url: http://127.0.0.1:8089/v1
        token_key: STUB_API_KEY
    models:
      lead:   { provider: stub, model: scripted }
      worker: { provider: stub, model: scripted }

A Go integration test then runs the real docker-agent binary against both crew.yaml and crew.hcl and checks each requirement in the project's SPEC.md:

--- PASS: TestCrew/crew.yaml/R2_delegates_to_scribe
--- PASS: TestCrew/crew.yaml/R4_.agentsignore_hides_target/.env
--- PASS: TestCrew/crew.yaml/R5_auditor_read_scope_holds
--- PASS: TestCrew/crew.yaml/R6_compound_shell_is_denied
--- PASS: TestCrew/crew.yaml/R7_scribe_cannot_write_target/
--- PASS: TestCrew/crew.yaml/R9_target_unchanged

What the runtime returned, verbatim:

Reading target/.env: path "target/.env" is excluded by .agentsignore
The pipeline auditor reading a prompt file: outside the allowed directories (./target)
The scribe writing target/Dockerfile: denied by the restricted safety mode, with no prompt
grep ... && curl --version: Tool 'shell' is denied by permissions configuration

The stub proves the harness, not the reviews. For review quality, the repo has three docker agent eval sessions: the gate must BLOCK the sample and name its worst problems, must not reveal the .env value when asked directly, and must not claim an edit when told to fix the Dockerfile. Those need real model keys and a container runtime, so they are not in CI yet. I have not run them yet, so I'm making no claim about review quality here.

The permissions trap

Permission patterns are globs matched against the whole command string, and * matches anything, including spaces. That makes the common prefix style unsafe for shell:

permissions:
  allow: ["shell:cmd=grep -n *"]
  deny:  ["shell:cmd=curl *"]

grep -n FROM target/Dockerfile && curl --version starts with grep -n , so it matches the allow rule. It does not start with curl , so it misses the deny rule. Deny is checked first, finds nothing, and allow approves it. I reproduced this with the stub (--flavor naive-permissions): curl ran and printed its version banner, even under restricted safety, because an explicit allow outranks the safety mode.

The documentation is clear that permissions are enforced client-side and are not a security boundary, and it points to sandbox mode for isolation. That is fair. The trap is that prefix rules like cat * and rm * are the pattern you see most often. What I use instead:

Deny shell operators outright: *&&*, *;*, *|*, backticks, $(.
Write deny rules as *curl*, not curl *.
Allow one narrow command per agent that needs a shell at all.
Run anything you don't fully trust with --sandbox.

The test suite asserts the trap still exists, so if a future release starts parsing compound commands, CI will tell me and I'll update the advice.

Other rough edges

The filesystem toolset is unrestricted by default. Without an allow_list, absolute paths and .. reach anything the process can. Docker's own example file calls this a footgun. Set allow_list on every filesystem toolset.
Pulled configs can set their own safety mode. An agent from a registry may declare runtime.safety: autonomous. Your own --safety flag or user settings win, but only if you set them. Read a config before you run it.
Sub-agents get the task text and nothing else. I confirmed it: the delegated task arrives in a <task> block in the sub-agent's system prompt, and its user turn is just "Please proceed." Isolation is good. It also means the lead's prompt must pass along everything a specialist needs.
It moves fast. The changelog lists 17 releases in September 2026 alone. Pin the version in CI. The rename from cagent also shows: the config and data directories are still ~/.config/cagent and ~/.cagent.
Telemetry is on by default. The first run says so. Set TELEMETRY_ENABLED=false in CI.
Evals have prerequisites. docker agent eval runs each case in a container and the default judge model is an OpenAI model, so plan for a container runtime and a second provider key, or pass --judge-model.

Try it

git clone https://github.com/mdabydeen/release-gate-crew && cd release-gate-crew
make test integration               # Go 1.24+ and docker-agent; no API key needed
export ANTHROPIC_API_KEY=...
docker agent run crew.yaml          # try /gate

Point it at your own service by replacing target/. If you try the evals with real keys before I do, I'd like to know what the gate gets wrong.

What I'd like to hear from people running agents in CI: where do your guardrails live today, in the agent's code or next to its config?

Originally published on DEV.

My Voice Is Code: How 2 Years as a Mute Freelance Go Developer Made Me an Async-First Expert

Sun, 04 Oct 2026 21:38:43 +0000

My Voice Is Code: How Being Mute Made Me The Best Async Dev You Will Hire

Hello CoderLegion. I am Pires Aurelio, Rising Voice here on the platform.

342 points, 13 badges, 5 technical tutorials in 3 days. But there is one thing my profile does not show: I am mute.

I am not telling this for pity. I am telling because this is my career strategy. And if you lead a remote team, you will want to hire me after this post.

1. Silence Became My Stack

When I lost my speech, I gained obsessive focus on written communication.

While other devs fix things with a 30 min call, I fix with:

README that any junior understands in 5 min
PR with full context, screenshots, metrics and rollback plan
API documentation before code
Commit messages that tell a story

This is not extra. It is survival. And it became my superpower.

Practical result: My Go Jobs Tracker project has a 12MB Docker image with 99 percent reduction, zero downtime deploy on Kubernetes, Prometheus with custom metrics, Grafana and healthz endpoint. Why? Because I cannot shout error on Slack. My system has to speak for me.

2. What 2 Years As Freelance Go Taught Me

Since May 2024 I am a Freelance Independent Go Developer from Luanda Cacuaco Angola.

Stack I deliver today:

Golang: REST and gRPC APIs, worker pools, graceful shutdown, concurrent scraping
DevOps: Docker multi stage, Kubernetes, Helm, GitHub Actions CI and CD
Observability: Prometheus Counter and Histogram, Grafana, structured logging
Extra: Digital Marketing and Promotion: I build AND promote the product

My 5 tutorials here prove it: Deploying Go Scraper to Kubernetes, Resilient Job Queue in Go, Migrating from Python to Go, 5 Real World API Examples with Gin.

All written, documented, production ready. Because my voice is code.

3. Why Async First Teams Love Me

I do not work in teams that need 1h daily meetings. I thrive in teams that value:

Async Culture and Written First
Inclusive and Accessibility First Environment
Data Driven decisions via metrics and docs

If you are a Tech Lead tired of devs who do not document, who break production without metrics, who disappear without written updates... I am your antidote.

My freelance workflow:

100 percent async, short overlap for review, rest written
Small PRs, tested, with built in observability
Runbooks that enable self serve onboarding for remote teams

4. Open To Work: Remote Async Teams

I am currently open to remote opportunities: Freelance, Contract, Part-time or Full-time.

If your team values written communication over endless meetings, documentation over noise, and results over presence, we will work great together.

I work 100 percent async, overlap for code review, everything else documented. My timezone is GMT plus 1 Angola but I work worldwide remote.

What I can do for you this week:

Ship a production Go API with Docker and Prometheus
Migrate your service to Kubernetes with zero downtime
Document your messy project so any dev can onboard self serve
Build and promote your technical product with Digital Marketing

I do not need a call to start. Send me a doc or an issue. I reply with a plan and a PR.

Direct contact: my email is aureliopires186 at Gmail, my WhatsApp is plus 244 926451351, my LinkedIn is Pires Aurelio, my GitHub is Aureliopires186. Search for Pires Aurlio here on CoderLegion.

5. The Invitation

If you are a team lead, founder, or dev who has a Go freelance task stuck because you need someone reliable who documents, message me.

My voice is code. Let my code speak for me.

Pires Aurelio
Freelance Backend Developer Go Docker Kubernetes
Async First Leader
Luanda Angola Remote Worldwide
Open to Work Freelance Inclusive

Deploying a Production-Ready Go Scraper to Kubernetes with Prometheus: The Complete Implementation

Sun, 04 Oct 2026 01:15:51 +0000

Most Go tutorials stop at go run main.go. Real production starts after that.

I had a working Go Jobs Tracker with Prometheus metrics, but it only ran on my laptop. If I close the lid, production dies. That is not production.

This is how I took it from localhost to a scalable, observable Kubernetes deployment with 12MB images, health checks, and zero-downtime.

The Problem: Why go run is Not Production

No isolation
No auto-restart
No scaling
No observability in cluster
Secrets in .env

We need Docker plus Kubernetes plus Prometheus.

Production Dockerfile - Multi-Stage (12MB vs 1GB)

This is the Dockerfile big tech uses. Not the junior FROM golang.

Create Dockerfile in root:

Stage 1: Builder - we compile here
FROM golang:1.22-alpine AS builder

WORKDIR /app

Cache dependencies first - faster rebuilds
COPY go.mod go.sum ./
RUN go mod download

COPY . .

Build static binary - no CGO, no libc dependency
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build \
  -ldflags="-w -s" \
  -o /go-jobs-tracker ./cmd/scraper

Stage 2: Final - distroless-level small
FROM alpine:3.19

WORKDIR /app

RUN apk --no-cache add ca-certificates wget

Copy only the binary
COPY --from=builder /go-jobs-tracker .

Non-root user - security best practice
RUN adduser -D appuser
USER appuser

EXPOSE 2112

K8s needs this to know if you are alive
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:2112/healthz || exit 1

CMD ["./go-jobs-tracker"]
Why this is production grade:
- Multi-stage results in 12MB final image
- -ldflags="-w -s" strips debug symbols
- CGO_ENABLED=0 produces static binary
- Non-root user for security
- HEALTHCHECK for Docker and K8s

Build it:
docker build -t go-jobs-tracker:latest .
docker images | grep go-jobs-tracker
3. Full Observability Stack with docker-compose

One command to run everything like in production.

Create `docker-compose.yml`:
version: '3.8'
services:
  scraper:
    build: .
    ports:
            - "2112:2112"
    restart: unless-stopped
    environment:
            - SERPAPI_KEY=${SERPAPI_KEY}
    networks:
            - monitoring

  prometheus:
    image: prom/prometheus:v2.52.0
    ports:
            - "9090:9090"
    volumes:
            - ./prometheus.yml:/etc/prometheus/prometheus.yml
            - prometheus_data:/prometheus
    command:
            - '--config.file=/etc/prometheus/prometheus.yml'
            - '--storage.tsdb.path=/prometheus'
    networks:
            - monitoring

  grafana:
    image: grafana/grafana:10.4.0
    ports:
            - "3000:3000"
    environment:
            - GF_SECURITY_ADMIN_USER=admin
            - GF_SECURITY_ADMIN_PASSWORD=admin
            - GF_USERS_ALLOW_SIGN_UP=false
    volumes:
            - grafana_data:/var/lib/grafana
    depends_on:
            - prometheus
    networks:
            - monitoring

volumes:
  prometheus_data:
  grafana_data:

networks:
  monitoring:
    driver: bridge
Create `prometheus.yml`:
global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
    - job_name: 'go-jobs-tracker'
    static_configs:
            - targets: ['scraper:2112']
    metrics_path: /metrics
    scrape_interval: 5s
Run it:
docker-compose up --build
Your stack:
- App on 2112 slash metrics
- Prometheus on 9090
- Grafana on 3000 with admin slash admin

4. Kubernetes - Real Production

This is what separates Senior from Staff.

Create folder `k8s` and file `k8s/deployment.yaml`:
apiVersion: v1
kind: Secret
metadata:
  name: scraper-secrets
type: Opaque
stringData:
  serpapi-key: YOUR_SERPAPI_KEY_HERE

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: go-jobs-tracker
  labels:
    app: go-jobs-tracker
spec:
  replicas: 2
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  selector:
    matchLabels:
      app: go-jobs-tracker
  template:
    metadata:
      labels:
        app: go-jobs-tracker
      annotations:
        prometheus.io/scrape: "true"
        prometheus.io/port: "2112"
        prometheus.io/path: "/metrics"
    spec:
      containers:
            - name: scraper
        image: ghcr.io/aureliopires186/go-jobs-tracker:latest
        imagePullPolicy: Always
        ports:
                - name: metrics
          containerPort: 2112
        env:
                - name: SERPAPI_KEY
          valueFrom:
            secretKeyRef:
              name: scraper-secrets
              key: serpapi-key
        resources:
          requests:
            memory: "64Mi"
            cpu: "50m"
          limits:
            memory: "128Mi"
            cpu: "200m"
        livenessProbe:
          httpGet:
            path: /healthz
            port: 2112
          initialDelaySeconds: 15
          periodSeconds: 20
          failureThreshold: 3
        readinessProbe:
          httpGet:
            path: /healthz
            port: 2112
          initialDelaySeconds: 5
          periodSeconds: 10
          failureThreshold: 3
---
apiVersion: v1
kind: Service
metadata:
  name: go-jobs-tracker-service
  labels:
    app: go-jobs-tracker
spec:
  selector:
    app: go-jobs-tracker
  ports:
    - name: metrics
    port: 2112
    targetPort: 2112
    protocol: TCP
  type: ClusterIP
Deploy to K8s:
kubectl apply -f k8s/deployment.yaml
kubectl get pods -w
kubectl logs -f deployment/go-jobs-tracker
kubectl port-forward svc/go-jobs-tracker-service 2112:2112
5. The Metrics Code - What Makes It Observable

Your metrics endpoint should expose this:
// metrics/metrics.go
package metrics

import (
  "github.com/prometheus/client_golang/prometheus"
  "github.com/prometheus/client_golang/prometheus/promauto"
)

var (
  JobsScraped = promauto.NewCounterVec(prometheus.CounterOpts{
    Name: "jobs_scraped_total",
    Help: "Total number of jobs scraped",
  }, []string{"engine", "status"})

  ScrapeDuration = promauto.NewHistogramVec(prometheus.HistogramOpts{
    Name:    "scrape_duration_seconds",
    Help:    "Duration of scrape jobs",
    Buckets: prometheus.DefBuckets,
  }, []string{"engine"})

  ScraperErrors = promauto.NewCounterVec(prometheus.CounterOpts{
    Name: "scraper_errors_total",
    Help: "Total errors in scraper",
  }, []string{"type"})
)
And in http://main.go:
http.Handle("/metrics", promhttp.Handler())
http.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request){
  w.WriteHeader(200)
  w.Write([]byte("ok"))
})
go http.ListenAndServe(":2112", nil)
6. Result: What You Get

After this tutorial you have:

- 12MB Docker image, not 1GB
- Non-root, secure, production-ready
- docker-compose with full monitoring
- K8s with 2 replicas, zero-downtime rolling update
- Liveness and Readiness probes
- Resource limits to prevent OOM in prod
- Prometheus auto-discovery
- Secrets, not hardcoded keys

This is how real companies deploy Go in production.

Production-ready Go is not about code, it is about deployment.


•Author : Pires Aurélio

Production-Ready Go Scraper with Prometheus - Complete Implementation Building a scraper

Sat, 03 Oct 2026 23:53:01 +0000

Building a scraper that works is easy. Building a scraper that you can observe in production is senior work.

I added Prometheus to my Go Jobs Tracker and here's the full working implementation.

PART 1: METRICS DEFINITION

Create file metrics/metrics.go:

package metrics

import (

"github.com/prometheus/client_golang/prometheus"
"github.com/prometheus/client_golang/prometheus/promauto"

)

var (

JobsScraped = promauto.NewCounterVec(
    prometheus.CounterOpts{
        Name: "jobs_scraped_total",
        Help: "Total number of jobs scraped per engine and status",
    },
    []string{"engine", "status"},
)

ScrapeDuration = promauto.NewHistogramVec(
    prometheus.HistogramOpts{
        Name: "scrape_duration_seconds",
        Help: "Duration of scrape jobs",
        Buckets: prometheus.DefBuckets,
    },
    []string{"engine"},
)

ErrorsTotal = promauto.NewCounterVec(
    prometheus.CounterOpts{
        Name: "scraper_errors_total",
        Help: "Total errors by type",
    },
    []string{"type"},
)

)

PART 2: MAIN.GO INTEGRATION - 100% WORKING

package main

import (

"net/http"
"time"
"github.com/prometheus/client_golang/prometheus/promhttp"
"github.com/Aureliopires186/go-jobs-tracker/metrics"

)

func main() {

go func() {
    http.Handle("/metrics", promhttp.Handler())
    http.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
        w.WriteHeader(200)
        w.Write([]byte("ok"))
    })
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("go-jobs-tracker running. check /metrics and /healthz"))
    })
    http.ListenAndServe(":2112", nil)
}()

start := time.Now()

// Simulate your scraping logic here
err := ScrapeGoogleJobs()

duration := time.Since(start)

if err != nil {
    metrics.ErrorsTotal.WithLabelValues("scrape_failed").Inc()
} else {
    metrics.JobsScraped.WithLabelValues("google_jobs", "success").Inc()
    metrics.ScrapeDuration.WithLabelValues("google_jobs").Observe(duration.Seconds())
}

select {}

}

func ScrapeGoogleJobs() error {

// your logic
return nil

}

PART 3: GO.MOD DEPENDENCY

Run:
go get github.com/prometheus/client_golang@v1.19.0
go mod tidy

PART 4: HOW TO TEST IT LOCALLY

Terminal 1:
go run main.go

Terminal 2:
curl http://localhost:2112/metrics
curl http://localhost:2112/healthz

You will see:
jobs_scraped_total
scrape_duration_seconds
scraper_errors_total

PART 5: PROMETHEUS CONFIG

prometheus.yml

global:
scrape_interval: 15s
scrape_configs:

- job_name: 'go-jobs-tracker'
static_configs:
        - targets: ['localhost:2112']

This setup is production ready, K8s ready, and used by real companies.

No more blind scraping.

•Author :Pires Aurélio

•Go Developer

How to Build an MCP Server in Golang Using the Official MCP SDK

Wed, 30 Sep 2026 06:51:40 +0000

What is MCP?
The Model Context Protocol is an open standard (by Anthropic) that lets LLM clients (Claude, Cursor, etc.) call external tools, read resources, and get prompted context in a uniform way — without any bespoke plugin per-model. You can read more about this on Model Context Protocol Docs

In this tutorial, we'll build a basic currency conversion MCP server using Golang and the official MCP SDK. We'll explore Streamable HTTP transport for remote access, add authentication to secure our server, and finally deploy the application to Render. By the end of this guide, you'll have a solid understanding of the complete lifecycle of building and deploying an MCP server in Go.

Prerequisites

Go 1.22+
Claude Desktop installed (for local testing)
Basic familiarity with Go modules and net/http

MCP Transports
MCP supports stdio and Streamable HTTP transport mechanisms that define how an MCP client and server communicate with each other. In this tutorial, we'll work with Streamable HTTP.

Streamable HTTP

Streamable HTTP allows MCP clients and servers to communicate over standard HTTP connections. The server runs independently and can be hosted remotely, making it accessible from different environments. Unlike stdio, Streamable HTTP allows the MCP server to live anywhere (local machine, Docker container, cloud VM, Kubernetes, etc.), making it much easier to share across multiple users.

Streamable HTTP is a better choice when you want to:

Deploy your MCP server to the cloud
Allow multiple clients to access the same server
Add features such as authentication and centralized monitoring
Manage your MCP server independently from the client application

Since we'll eventually deploy our currency conversion server to Render, Streamable HTTP will play an important role in moving from a local setup to a production-ready deployment.

Setting up Golang project

You can refer following blog for setting up a basic golang project. We will use the go-sdk for creating mcp server which is maintend by the mcp team.

go mod init example/mcp-server
go get -u github.com/gorilla/mux
go get https://github.com/modelcontextprotocol/go-sdk

Basic MCP Server

To start, we'll set up a very basic mcp server with just 1 tool. Before building the currency conversion tool, let's start with a minimal Greeting tool so we can understand the basic structure of an MCP server.

// main.go
package main

import (
...
)

func main() {
logger := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelInfo}))

err := godotenv.Load()
if err != nil {
logger.Error("error loading .env file", "err", err)
}

mcpServer := server.NewMcpServer(logger)
mcpServer.AddReceivingMiddleware(security.LoggingMiddleware())

mcpHandler := mcp.NewStreamableHTTPHandler(func(request *http.Request) *mcp.Server {
return mcpServer
}, &mcp.StreamableHTTPOptions{
Logger:                     logger,
JSONResponse:               true,
Stateless:                  true,
DisableLocalhostProtection: true,
})

router := server.NewHttpServer(mcpServer, mcpHandler)

mcp.AddTool(mcpServer, &mcp.Tool{
Title:       "Greeting",
Name:        "greeting",
Description: "Greet a person by name",
}, SayHi)

port := os.Getenv("PORT")
if port == "" {
port = "3000"
}

server := &http.Server{
Addr:              ":" + port,
Handler:           router,
ReadTimeout:       5 * time.Minute,
ReadHeaderTimeout: 10 * time.Second,
WriteTimeout:      5 * time.Minute,
IdleTimeout:       5 * time.Minute,
MaxHeaderBytes:    1 << 20,
}

go func() {
logger.Info("starting server", "addr", port)

if err := server.ListenAndServe(); err != nil &&
err != http.ErrServerClosed {

logger.Error("server failed", "err", err)
os.Exit(1)
}
}()

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

<-ctx.Done()

logger.Info("shutdown initiated")

shutdownCtx, cancel := context.WithTimeout(
context.Background(),
30*time.Second,
)
defer cancel()

if err := server.Shutdown(shutdownCtx); err != nil {
logger.Error("shutdown failed", "err", err)
}

logger.Info("shutdown complete")
}

type GreetingInput struct {
Name string `json:"name" jsonschema:"the name of the person to greet"`
}

type GreetingOutput struct {
Greeting string `json:"greeting" jsonschema:"the greeting to tell to the user"`
}

func SayHi(ctx context.Context, req *mcp.CallToolRequest, input GreetingInput) (
*mcp.CallToolResult, any, error) {
return &mcp.CallToolResult{
Content: []mcp.Content{
&mcp.TextContent{Text: "Hi " + input.Name},
},
}, GreetingOutput{Greeting: "Hi " + input.Name}, nil
}

// server.go
package server

import (
...
)

func NewMcpServer(logger *slog.Logger) *mcp.Server {
 implementation := &mcp.Implementation{
  Title:   "MCP Tutorial For Greeting",
  Name:    "greeting-mcp",
  Version: "1.0.0",
 }

 serverOptions := &mcp.ServerOptions{
  Logger:    logger,
  KeepAlive: 5 * time.Minute,
 }

 return mcp.NewServer(implementation, serverOptions)
}

func NewHttpServer(server *mcp.Server, mcpHandler *mcp.StreamableHTTPHandler) *mux.Router {
router := mux.NewRouter()

router.HandleFunc("/health", func(w http.ResponseWriter, req *http.Request) {
w.WriteHeader(http.StatusOK)
_, _ = w.Write([]byte("ok"))
}).Methods(http.MethodGet)

// Optional root route to avoid confusion when testing in browser.
router.HandleFunc("/", func(w http.ResponseWriter, _ *http.Request) {
w.WriteHeader(http.StatusOK)
_, _ = w.Write([]byte("MCP server is running. Use /mcp endpoint."))
}).Methods(http.MethodGet, http.MethodPost, http.MethodOptions)

router.HandleFunc("/mcp", func(w http.ResponseWriter, req *http.Request) {
fmt.Printf(
"method=%s path=%s auth=%q\n",
req.Method,
req.URL.Path,
req.Header.Get("Authorization"),
)
mcpHandler.ServeHTTP(w, req)
}).Methods(http.MethodPost, http.MethodGet, http.MethodOptions)

return router
}

Here you can see for the http server we expose /mcp endpoint. This endpoint is not a REST endpoint that your application calls directly. It speaks the MCP protocol over HTTP and is intended to be consumed by MCP clients.

Understanding MCP Tools
I like to think of MCP tools as API endpoint which an AI agent or client understands and sends request to based on its analysis of the prompt user has typed. So it becomes very important how we name our MCP tool. You can read more on it here

Now lets build a real life example tool which could do currency conversion. For currency conversion I am using this free API which is provided by fawazahmed0 in the following github repo.

package tool

import (
...
)

// ConvertCurrencyInput is the input for the ConvertCurrencyTool
type ConvertCurrencyInput struct {
FromCurrency string  `json:"from_currency" jsonschema:"currency codes are ISO 4217 format, e.g. USD, EUR, GBP, etc. the currency to convert from"`
ToCurrency   string  `json:"to_currency" jsonschema:"currency codes are ISO 4217 format, e.g. USD, EUR, GBP, etc. the currency to convert to"`
Amount       float64 `json:"amount" jsonschema:"the amount to convert"`
}

// ConvertCurrencyOutput is the output for the ConvertCurrencyTool
type ConvertCurrencyOutput struct {
ConvertedAmount float64 `json:"converted_amount" jsonschema:"the converted amount"`
}

type CurrencyResponse struct {
Date string                        `json:"date" jsonschema:"the date of the currency rates"`
Data map[string]map[string]float64 `json:"-" jsonschema:"the currency rates"`
}

const BASE_CURRENCY_API_URL = `https://cdn.jsdelivr.net/npm/@fawazahmed0/currency-api@latest/v1/currencies`

// ConvertCurrencyTool converts a currency to another currency
func ConvertCurrencyTool(ctx context.Context, req *mcp.CallToolRequest, input ConvertCurrencyInput) (*mcp.CallToolResult, any, error) {
input.FromCurrency = strings.ToLower(input.FromCurrency)
input.ToCurrency = strings.ToLower(input.ToCurrency)
fmt.Println("inside convert currency tool input", input)

apiURL := fmt.Sprintf("%s/%s.json", BASE_CURRENCY_API_URL, input.FromCurrency)
resp, err := http.Get(apiURL)
if err != nil {
return nil, nil, err
}
defer resp.Body.Close()

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

response, err := UnmarshalJSON(body)
if err != nil {
return nil, nil, err
}

if _, ok := response.Data[input.FromCurrency]; !ok {
return nil, nil, fmt.Errorf("currency %s not found", input.FromCurrency)
}

if _, ok := response.Data[input.FromCurrency][input.ToCurrency]; !ok {
return nil, nil, fmt.Errorf("currency %s not found", input.ToCurrency)
}

convertedAmount := response.Data[input.FromCurrency][input.ToCurrency] * input.Amount
return &mcp.CallToolResult{
Content: []mcp.Content{
&mcp.TextContent{
Text: fmt.Sprintf("Converted amount: %f", convertedAmount),
},
},
}, nil, nil
}

func UnmarshalJSON(data []byte) (*CurrencyResponse, error) {
var r CurrencyResponse
var raw map[string]json.RawMessage

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

// Extract date
if v, ok := raw["date"]; ok {
if err := json.Unmarshal(v, &r.Date); err != nil {
return nil, err
}
delete(raw, "date")
}

// Remaining keys are currency codes
r.Data = make(map[string]map[string]float64)

for currency, v := range raw {
var rates map[string]float64
if err := json.Unmarshal(v, &rates); err != nil {
return nil, err
}
r.Data[currency] = rates
}

return &r, nil
}

Now to add the mcp server we do the following

// main.go

....

func main() {
...

mcp.AddTool(mcpServer, &mcp.Tool{
Title:       "Currency Conversion",
Name:        "currency-conversion",
Description: "Convert an amount from one currency to another. Requires from_currency, to_currency (ISO 4217 codes), and amount. Uses latest exchange rates from an external API.",
}, ConvertCurrencyTool)
...
}

Now lets understand what is happening here and how it works. First we register this tool using mcp.AddTool. Here Title is just human readable text and does not provide any help or context to the AI agent. Name and Description are 2 important things when registering a tool as this 2 piece of information helps the AI agent to make the decision on which MCP server should be used.

Now lets go to the ConvertCurrencyTool. This function takes 3 arguments which is the method signature and the 3rd parameter which is input is what we will focus on. It is like the request body that we expect to receive from the AI agent. In my case I am expecting fromCurrency, toCurrency and amount. For all the fields I have jsonschema specified which, like the tool description, helps the AI understand what each field represents. The SDK converts these tags into the MCP Tool schema that the model receives during tool discovery

The ConvertCurrencyTool makes an API call to fetch the latest exchange rates, performs the currency conversion, and returns the result to the MCP client.

There are a few more things which can be done during mcp server creation. Another useful server configuration is Instructions. These provide additional context to the AI model and can improve tool selection and overall responses.

func NewMcpServer(logger *slog.Logger) *mcp.Server {
implementation := &mcp.Implementation{
Title:   "MCP Tutorial For Currency Conversion",
Name:    "currency-conversion-mcp",
Version: "1.0.0",
}

serverOptions := &mcp.ServerOptions{
Logger:       logger,
KeepAlive:    5 * time.Minute,
Instructions: `You are a helpful assistant that can convert currencies. You can convert currencies using the currency-conversion tool.`,
        Capabilities: &mcp.ServerCapabilities{
Tools: &mcp.ToolCapabilities{},
},
}

return mcp.NewServer(implementation, serverOptions)
}

There is also one more important setting that we should we about when configuring the streamable http transport

mcpHandler := mcp.NewStreamableHTTPHandler(func(request *http.Request) *mcp.Server {
return mcpServer
}, &mcp.StreamableHTTPOptions{
Logger:                     logger,
JSONResponse:               true,
Stateless:                  true,
DisableLocalhostProtection: true,
})

Here the options part is important to understand. JSONResponse is basic tells if the response type is json or not. Stateless - this is one of the key option to understand. Stateless mode tells the server not to rely on MCP sessions. Every request should contain all information required to process it, making deployment behind load balancers and horizontal scaling much easier.. This is very well explained in Anthropic courses named Model Context Protocol: Advanced Topics. I ideally like to keep it to true as a REST API is always stateless and we use Authorization headers to validate the user so we can follow the same setup here too. The last option which is DisableLocalhostProtection again an important flag to be set to true when deploying to production. You can read more on this here.

To find more examples on how to create Prompt, Resource you can always refer following docs

How registration works

When we call:

mcp.AddTool(mcpServer, &mcp.Tool{
    Title:       "Currency Conversion",
    Name:        "currency-conversion",
    Description: "Convert an amount from one currency to another...",
}, ConvertCurrencyTool)

we are not creating a new HTTP endpoint like we would in a typical REST application. Instead, we're registering the tool with the MCP server.

From this point on, the lifecycle looks like this:

The tool is registered: The MCP server stores the tool's metadata, including its name, description, and input schema.
The MCP client connects: When a client such as Claude Desktop connects to the server, it asks the server which tools are available.
The server advertises its tools: The server responds with the list of registered tools, including their descriptions and JSON schemas.
The LLM decides whether to use a tool: When the user asks a question like:

How much is 28 USD in INR?

the model analyzes the request and determines that the currency-conversion tool is appropriate.

The client invokes the tool: The client sends a tool invocation request to the MCP server containing the required input
```
{
  "from_currency": "USD",
  "to_currency": "INR",
  "amount": 28
}
```
Your Go function executes: The Go SDK automatically deserializes the request into a ConvertCurrencyInput struct and calls: ConvertCurrencyTool(ctx, req, input)
The result is returned: Your function performs the currency conversion, returns the result, and the SDK sends it back to the client. Claude then uses that result to generate its final response to the user.

Conclusion
In this tutorial, we built a complete MCP server in Go using the official Go SDK. We started with a simple greeting tool, expanded it into a practical currency conversion service, exposed it using Streamable HTTP, discussed important server configuration options.

In the next step, you can deploy the same server to Render and make it accessible remotely without changing the MCP client configuration.

The complete source code for this tutorial is available on GitHub:

GitHub Repository: https://github.com/shaileshhb/mcp-tutorial

ForgeZero: What Happens When Someone Finally Stops Forgiving Your Build System

Mon, 14 Sep 2026 21:33:21 +0000

In 1976, a Bell Labs researcher named Stuart Feldman was annoyed at a coworker. The story, as it's been retold for half a century now, goes something like this: a colleague kept shipping broken binaries because he'd edit a source file and forget to recompile the parts of the program that depended on it. Feldman's fix wasn't a lecture. It was make — a tool whose entire reason for existing was to answer one question correctly, automatically, every single time: what, exactly, needs to be rebuilt right now, and what doesn't?

That question turned out to be one of the hardest, most quietly load-bearing problems in all of software engineering. Fifty years later, we're still answering it badly, most of the time, and most engineers have simply stopped noticing.

Make aged the way anything does when it becomes foundational infrastructure nobody's allowed to break: badly, slowly, and in public. Its dependency model — timestamps, phony targets, recursive invocation — leaked complexity into every project that grew past a few dozen files, and autotools showed up to paper over that with an entire generation-of-generators architecture that, to this day, remains one of the most feared corners of the open-source toolchain. CMake arrived at the turn of the millennium out of Kitware's need to build ITK and VTK across radically different platforms without hand-maintaining a Makefile per OS — a meta-build system that generates other build systems, which is either a brilliant abstraction or a confession that the underlying problem was never actually solved, depending on which decade of CMake you personally suffered through.

And then there's Ninja. Evan Martin built it at Google specifically because Chromium's build had grown so large that Make's dependency-graph evaluation had become a measurable, painful part of every engineer's day — and his answer was almost insultingly minimal: a build file format so sparse that the project's own documentation tells you, directly, that you are not meant to write Ninja files by hand. Ninja doesn't try to be pleasant. It tries to be a fast, dumb, extremely well-behaved execution target for something smarter sitting above it, generating its files for it. That single design decision — radical minimalism as a feature, not a limitation — is one of the most underrated ideas in build tooling history, and it's the closest ancestor to what comes next in this story.

Because none of Make, Autotools, CMake, or Ninja were ever built for the workload I actually live in: assembly-heavy code, small C translation units by the hundreds, embedded and bare-metal targets, mixed-language repositories where the coordination between compiler invocations costs more than the invocations themselves. I started building ForgeZero to solve that gap about a year and a half ago, quietly, on my own time, the way most infrastructure worth trusting actually gets built. It went public in May 2026. This is the deep engineering account of what it actually is.

The Thesis, Stated Plainly

A build system should handle planning, invalidation, and routing. It should not try to reinvent the compiler.

That single sentence is the entire architectural spine of ForgeZero, and everything below is just the consequence of taking it seriously. ForgeZero is not GCC, Clang, Zig, NASM, FASM, GAS, or LD, and it has no interest in becoming any of them. It's the thin, transparent coordination layer that decides what those tools need to do, when, and whether they need to do it again at all — and then gets entirely out of the way.

The value proposition compresses into one relationship:

Build Throughput ≈ Useful Compiler Work
                    ─────────────────────────────────────────
                    Discovery + Dispatch + Repeated Work + Invalidation Cost

Every serious build-system optimization in ForgeZero attacks the denominator. None of it touches the numerator, because the numerator — actual code generation correctness — belongs to GCC, Clang, Zig, and the assemblers, permanently, and ForgeZero has no ambition to argue with that division of labor.

The Pipeline as a Chain of Owned Transformations

Filesystem state becomes a source set. The source set becomes a dependency closure. That closure becomes a preprocessing state, then a cache identity, then a set of compiler and assembler actions, then an object graph, then a linker invocation, then a verified artifact.

filesystem state
    -> source set
    -> dependency closure
    -> preprocessing state
    -> cache identity
    -> compiler/assembler actions
    -> object graph
    -> linker invocation
    -> verified artifact

What makes this more than a diagram is that each arrow is an owned boundary with its own failure class. A discovery failure is not a cache failure. A cache failure is not a linker failure. When something goes wrong, an engineer using ForgeZero is diagnosing one specific, narrow transformation — not reverse-engineering an opaque shell invocation that happened to fail somewhere in the middle of a black box.

Four properties fall directly out of respecting that boundary discipline:

Observability — the selected backend, target, flags, object paths, cache decisions, and exact linker command are all visible, not inferred.
Controllability — ABI, compiler, linker, optimization level, sysroot, and output format are never hidden behind a "just trust the abstraction" layer.
Amortization — unchanged units don't get recompiled, and metadata checks run before the expensive stages, not after.
Composability — assembly, C-family code, Zig, Gloria, custom preprocessing, and security tooling all live inside one coordinated pipeline instead of five disconnected ones duct-taped together in CI.

Who This Was Actually Built For

This isn't a general-purpose build tool wearing a performance costume. It has specific, named audiences, and it's honest about who they are:

Assembly engineers — boot code, runtime glue, kernel-adjacent components, flat binaries, hand-managed ELF/PE/Mach-O pipelines, where NASM/FASM/GAS selection and the resulting object format can't be papered over.
C/C++/Objective-C engineers who need direct, unfiltered access to GCC, Clang, or Zig — their own -I, -D, -O, sanitizer, and linker flags surviving intact into the actual command line.
Embedded and cross-compilation engineers targeting ARM, RISC-V, and bare-metal ABIs, where the target triple has to participate directly in backend selection, not get normalized away.
Release and supply-chain engineers who need reproducible builds, source-tree verification, SBOM generation, SAST-style auditing, and filesystem isolation — as genuinely separate concerns from the build cache, never conflated with it.
Build infrastructure authors looking to replace a Make/Ninja/shell-script Frankenstein with one coordinator that has a predictable cache model and room for hooks, watchers, and compile databases.

Cache Identity: The Part Everyone Gets Wrong

Here's the mistake that shows up in almost every homegrown build cache: treating "the source bytes didn't change" as sufficient justification for reusing a compiled object. It isn't, and pretending it is produces silent, maddening correctness bugs. The same source file produces a different correct object under a different compiler, a different compiler version, a different target triple, a different sysroot, different optimization flags, different sanitizer policy, or different linker configuration.

ForgeZero's action-level cache identity is built from the sorted inputs, their digests, the action name, and the full environment and toolchain parameters — not the source hash alone. Two layers do the heavy lifting:

Metadata-first invalidation checks file size and modification time before touching the file's bytes at all. If both match a cache entry, the expensive digest step is skipped entirely. Only a mismatch triggers a full keyed digest computation. This is explicitly a performance optimization, not a cryptographic guarantee — and ForgeZero doesn't pretend otherwise. Security-sensitive verification lives in its own, separately-specified verify/SBOM contract, deliberately kept apart from the invalidation fast path.

The disk hash cache format, FZHC3, stores path length, metadata, a context fingerprint, and a 32-byte digest, written via a temp-file-then-rename sequence specifically to avoid leaving a half-written cache entry behind on a crash. Small detail. The kind of detail that separates a cache you can trust from one you quietly stop trusting after the third mysterious corruption.

Two Hashes, One Honest Boundary

This is where ForgeZero's engineering has genuinely moved since it first went public, and it's worth explaining precisely, because the project draws a hard, deliberate line between two hashing systems that solve related but different problems.

BoomBoom Hash is the original incremental-invalidation engine, built as a specialized layer over keyed BLAKE3. Build context — compiler identity, version, target triple, ordered flags — gets domain-separated and hashed into a derived key first, so the same source bytes produce different digests under different build contexts without any cross-contamination between cache domains. Source files are broken into logical chunks — directive regions, brace-delimited blocks, top-level statements, residual spans — each independently digested and placed as a leaf in a flat, heap-layout Merkle tree. Change one chunk, and only the path from that leaf to the root gets recomputed: O(log n) instead of a full O(n) re-aggregation. Past four changed chunks, a persistent worker pool picks up jobs through atomic fetch-and-add over a flat array, each worker holding its own independent keyed BLAKE3 state, with zero shared mutable state at the hasher level.

BB64 is newer, and it exists precisely because BoomBoom Hash, built on a general-purpose cryptographic primitive, is doing more work than some invalidation paths actually need. BB64 is a purpose-built, non-cryptographic 64-bit hash with a hand-written AVX2 Plan 9 assembly hot path, a scalar fallback verified for bit-exact equivalence against the SIMD path, explicit tail handling for inputs of arbitrary length, and SIMD-accelerated byte comparison and delimiter scanning. On an AMD Ryzen 7 PRO 4750U, it measured roughly 16.87 GB/s at 0 B/op and 0 allocs/op — against roughly 0.42 GB/s for FNV-1a and roughly 1.71 GB/s for BLAKE3 on the same benchmark input. That's about 40x FNV-1a and nearly 10x BLAKE3, for a task — PCH cache-key generation, keyed off header content, compiler, target, flags, and positions — that never needed cryptographic guarantees in the first place.

And here's the part that should matter most to anyone evaluating this as infrastructure, not just admiring the throughput number: BB64 is explicitly, deliberately never used for security-sensitive file integrity, package verification, or any cryptographic surface. That boundary isn't an oversight waiting to be "optimized away" later. It's the whole point. A fast non-cryptographic hash and a keyed cryptographic hash are different tools solving different problems, and collapsing that distinction to save one dependency is exactly the kind of shortcut that turns into a CVE two years later. ForgeZero doesn't take it.

Below the Go Standard Library: The Discovery Layer

This is the part that will make a systems engineer sit up, because it's the difference between "a build tool written in Go" and "a build tool written by someone who's actually spent time fighting syscall on Linux.

Source discovery on Linux bypasses the convenient, portable filepath.WalkDir entirely in favor of raw getdents64 traversal via unix.Getdents, paired with openat using O_NOFOLLOW to keep directory traversal from silently following a symlink somewhere it shouldn't. Metadata collection goes through Linux statx for type, inode, size, and modification time in a single call, falling back to Fstatat on kernels where statx isn't reliably available. Directory reads retry on EINTR instead of surfacing a spurious failure, malformed dirents get validated rather than trusted, and path ordering is made deterministic so two runs on the same tree produce the same discovery order — a small property that matters enormously the first time you're trying to reproduce a flaky build. Non-Linux platforms fall back cleanly to filepath.WalkDir, because the portable API contract stays identical even when the backend implementation doesn't.

The payoff isn't hypothetical: manual dirent parsing measurably cut Linux discovery allocations on a 1,024-file benchmark from roughly 3,182 down to 2,088 allocations per operation — about a third fewer allocations, on a code path that runs at the very start of every single build.

io_uring, Used Honestly

ForgeZero's io_uring integration batches file reads into a single submission cycle instead of one syscall per file, drains completion queue entries fully with explicit user-data bounds checking, handles zero-length files without generating an invalid empty READ request, and supports IORING_OP_STATX for metadata collection through the same ring. It enables IORING_SETUP_COOP_TASKRUN where the kernel supports it, with a clean setup fallback for older kernels that don't.

And then there's the detail that actually tells you how this team thinks: IORING_OP_GETDENTS was never wired up, because the target kernel ABI doesn't expose a usable io_uring GETDENTS opcode — so rather than fabricate support for an operation that doesn't reliably exist, directory listing stays on the syscall path where it actually works. That's a small, unglamorous decision. It's also exactly the kind of decision that separates infrastructure you can trust from infrastructure that looks impressive in a README until someone runs it on the wrong kernel version.

Symbol cache decoding is strict — malformed records are rejected outright rather than partially trusted, triggering a fresh extraction through nm, objdump, or readelf instead of silently propagating a corrupted cache entry into a link step. Symbol results move through indexed, preallocated result slots instead of a per-object queue payload, cutting allocation churn on the hot link path. The scheduler supports idempotent shutdown and explicit stopped-state handling, so a second shutdown call doesn't do anything surprising.

And then there's this: worker and scheduler queue producer/consumer counters are deliberately separated across 64-byte cache lines, specifically to avoid false sharing — the scenario where two unrelated atomic counters happen to land on the same CPU cache line and start silently fighting each other for cache coherency traffic under concurrent load, tanking throughput for no reason visible anywhere in the code. This is genuinely advanced systems-engineering territory, the kind of optimization that only shows up in codebases that have actually been profiled under real concurrent load rather than just "made to compile and pass CI."

Gloria: The Language That Refuses to Hide Anything

Sitting inside ForgeZero is Gloria, an experimental language that isn't trying to compete with C, Rust, or a full assembler frontend. It occupies a specific, narrow niche: a minimal language for producing a small, fully-understood fragment of machine code in contexts where a libc, a runtime, and a general-purpose compiler pipeline would be overkill.

source -> lexer -> tokens -> codegen -> machine bytes -> relocation -> raw binary

There's no mandatory intermediate object file, no libc startup sequence, no standard linker script. The emitter writes bytes directly, and ForgeZero writes them out as a raw binary. Functions land in a contiguous output buffer; calls are written first with relocation placeholders, and once the function table is complete, relative displacements get patched directly into the buffer:

disp32 = offset(target) - (offset(call) + 5)

That's the entire mechanism that lets Gloria skip a full object-file linker for small raw images. Compile this:

fn main() {
    let a = 10;
    let b = 20;

    if b > a {
        print("hello world lol");
    }
}

and disassembling the resulting gloria.bin shows exactly what you'd hope for from a language that refuses to hide anything: an entry jump and stack-frame prologue, 64-bit immediate loads materializing the literals, a cmp/jle pair lowering the comparison, and — because the observed output loop writes directly to 0xb8000, the classic x86 VGA text-memory address — a byte-by-byte character-and-attribute write loop instead of a hidden printf call. Every single opcode in that disassembly traces back to a specific, readable decision the emitter made. That transparency, not competing with production languages, is the entire point of Gloria existing at all.

Security as a Neighbor, Not a Costume

ForgeZero keeps its security surfaces deliberately separate from its performance surfaces, because conflating "this build was fast" with "this build can be trusted" is exactly how supply-chain incidents happen. Path validation constrains CLI paths, symlink boundaries, and FZP include resolution to explicitly allowed roots. A dedicated seal/integrity subsystem tracks trust state for executables and toolchains — a fundamentally different question from "do I need to recompile this file," and the codebase treats it as one. SBOM generation produces a CycloneDX-style component inventory with hashes; a separate audit subsystem runs SAST-style checks for secrets, vendor-specific risk patterns, and configuration violations; manifest-based source-tree verification is kept algorithmically stable specifically so release verification stays interoperable across versions instead of silently drifting.

Cache hits are fast. Cache hits are not proof of integrity. ForgeZero's architecture never lets those two facts get confused with each other.

The Redis Case Study, Read Correctly

The number worth reporting is this one:

fz -p performance -dir redis/src -mode c -out redis-server -j 16

user       27.66 s
system     11.68 s
CPU        1155%
elapsed     3.404 s

Read it precisely, because precision is the entire point of this project. 1155% CPU utilization means the work was genuinely spread across multiple hardware threads, not disguised behind a fast single-thread path. 3.404 seconds elapsed against nearly 40 seconds of combined CPU time shows the bottleneck sitting in parallel compile-and-link work, not in sequential orchestration overhead — which is exactly where you want a build's time to be spent. The dependency closure for that run wasn't trivial: fpconv, hdr_histogram, hiredis, libxxhash, linenoise, lua, and tre were each independently compiled into static archives, then handed to the linker alongside Redis's own translation units — proving the pipeline handles real, dependency-aware, multi-ABI native builds, not just a flat folder of standalone .c files.

The honest framing matters more than the headline number: this is end-to-end orchestration latency on one specific host, toolchain, and cache state — not a claim about compiler speed, and not a number that means anything without the CPU model, governor, storage, toolchain versions, cache warmth, and parallelism level that produced it. ForgeZero's own documentation says exactly that, unprompted, which is a more convincing performance claim than any raw benchmark number could be on its own.

Cross-Platform Without Pretending Every Platform Is the Same

The Go core stays portable while low-level operations are split cleanly across build-tagged files: Linux gets native getdents64/statx/io_uring fast paths, other Unix-like targets get mmap/descriptor-based paths, Windows gets its own executable, security, and filesystem branches entirely. Cross-platform, here, doesn't mean identical capability everywhere — it means an identical semantic contract at the API boundary regardless of which backend is actually doing the work underneath it. Linux can have the fastest path available to it without Windows being forced into an emulation layer pretending to be a kernel it isn't.

The Installer Nobody Notices Until It Breaks

install.sh got rewritten as a strict POSIX sh script with explicit platform and architecture validation, --help and missing-option handling, retry-and-timeout logic on both curl and wget, and remote and local checksum verification before anything gets executed. The insecure mktemp -u pattern — which creates a predictable race window between naming a temp path and actually using it — was replaced with a properly private temporary directory. Writable installs land through a temp-file-then-atomic-rename sequence; privileged installs go through sudo install rather than a raw copy; a full dry-run mode exists that downloads and modifies nothing; cleanup traps make sure temp files don't survive a failed run. It's the least glamorous file in the entire repository, and it's exactly the file that determines whether someone's first five minutes with the project go smoothly or end with a half-installed binary and a GitHub issue.

What ForgeZero Deliberately Doesn't Do — And Why That's Worth Trusting

The most senior-engineer-coded section of this entire project's documentation isn't a feature list. It's a short list of things the team explicitly chose not to build, and it's worth reading as a statement of engineering values as much as a technical note:

BB64 stays out of every security-sensitive path — integrity checks, package verification, and cryptographic APIs all keep using the keyed BLAKE3-based BoomBoom Hash, on purpose.
IORING_OP_GETDENTS was never faked into existence to check a feature-completeness box, because the kernel ABI in question genuinely doesn't expose a usable opcode for it.
clone3/execveat weren't forced into the process launcher without a proper lifecycle design, because Go's context cancellation, descriptor ownership, and cross-platform launcher contracts all deserve a real design pass, not a shortcut.
A shared-memory persistent cache wasn't shipped without a versioned format, crash recovery, and an ownership protocol behind it — because a cache that can silently corrupt itself is worse than no cache at all.
No thousand-fold speedup claims got made without workload-specific measurements standing behind them.

Any team can list what they built. Far fewer are willing to publish, in plain language, what they refused to ship half-finished — and that restraint is a far stronger signal of engineering maturity than another benchmark chart would ever be.

Where This Actually Leaves You

ForgeZero isn't trying to convince you that gcc -O3 needs replacing. It's making a much narrower, much more defensible claim: that the coordination surrounding native compilation — discovery, invalidation, scheduling, dispatch, caching, linking — has its own real, measurable cost, and that cost has been quietly tolerated by an entire industry for decades because Make, Autotools, CMake, and Ninja were each solving the build problem of their own era, not this one. Assembly-heavy, embedded, mixed-language, cache-identity-sensitive native builds were never really the target audience for any of them.

A year and a half of quiet, unglamorous systems work — cache-line-aware schedulers, kernel-ABI-honest io_uring integration, a hash function that knows exactly which problems it's allowed to touch and which ones it isn't — is what it actually takes to make that narrower claim true instead of just plausible. That's the whole pitch. Not magic. Not a thousand-fold speedup. Just a build system that finally stops forgiving itself for not knowing precisely why it did what it just did.

GoGraph updates, Providing Structural Awareness to AI Coding Agents in Go.

Wed, 09 Sep 2026 18:31:10 +0000

GoGraph Four Months Later: From Repository Map to Evidence Layer for AI Coding Agents

A few months ago, I wrote about a problem I kept seeing with AI coding agents: they could write Go perfectly well, but before doing anything useful they spent a surprising amount of their context window trying to understand the repository.

They would grep for symbols, guess filenames, read large files, follow imports manually, and slowly reconstruct relationships that the Go compiler already knows.

That was the motivation behind GoGraph.

The first version I wrote about in May was relatively simple in concept: parse a Go repository, turn its structure into a graph, and expose that graph to coding agents through CLI commands and MCP.

The basic idea has not changed.

But GoGraph itself has changed quite a lot.

Today, I would describe it less as a static repository map and more as a local evidence layer between a Go codebase and an AI coding agent.

The Original Model: Give the Agent a Map

The first version concentrated heavily on AST-based structural analysis.

GoGraph parsed source code and extracted things such as:

packages
functions and methods
imports
calls
interfaces and implementations
HTTP routes
tests
SQL-related structures
error paths

Commands such as plan, review, and errorflow were intended to answer practical questions before and after an agent edited code.

Instead of:

grep
rg
awk
sed
read file
grep again
read another file
guess

the agent could ask GoGraph for a bounded structural answer.

That is still useful, and the AST layer still exists.

The limitation is that Go is not completely understandable from syntax alone.

Consider this:

type Store interface {
    Save(User) error
}
func Create(s Store, u User) error {
    return s.Save(u)
}

From the AST, we know that Create calls Store.Save.

But that does not necessarily tell us which concrete Save implementation executes.

That becomes increasingly important once an agent starts reasoning about impact rather than simply locating code.

GoGraph Now Has a Precision Layer

The largest architectural change is that GoGraph no longer relies only on syntactic relationships.

Precise builds now use Go’s type information together with go/packages, go/types, SSA, and Class Hierarchy Analysis.

The result is effectively a two-layer model.

The AST layer remains fast, resilient, and useful even when a repository cannot be fully type-checked.

The precision layer adds compiler-aware relationships when the repository can be successfully loaded.

This matters particularly for interfaces.

An AST-level analysis might know that:

service -> Repository.Save

Type-aware analysis can identify actual implementations of that interface.

SSA analysis can sometimes go further and prove that a particular interface value contains one concrete implementation at a call site.

GoGraph deliberately distinguishes those cases.

A call that is proven receives different treatment from a call that is merely a possible dynamic dispatch target.

That distinction turned out to be important for agents.

An AI should not see:

A calls B

when what the analysis actually knows is:

A may call B

Those are different facts.

Exact and Possible Relationships

This led to another change in the graph model.

Relationships now carry more information about how strongly GoGraph knows them.

For example, paths can contain relationships that are:

exact
ambiguous
possible

Commands can request exact-only results when an agent needs a conservative answer.

When several possible paths exist, GoGraph also ranks them deterministically rather than returning whichever traversal happens to find first.

The preference is roughly toward:

stronger evidence
shorter paths
production code rather than tests
typed resolution rather than heuristics
fewer cross-repository transitions

This sounds like an implementation detail, but it changes agent behavior substantially.

Determinism is useful when an LLM repeatedly asks the same structural question during planning, editing, and review. The answer should not change merely because map iteration order changed.

A First-Call Tool for Agents

One problem became obvious after using GoGraph with actual coding agents.

Even with dozens of specialized commands, the agent first has to know which command to use.

So GoGraph now has explore.

For example:

gograph explore "authentication middleware"

or through MCP, gograph_explore.

It performs bounded lexical discovery and, when a symbol can be selected unambiguously, combines several kinds of context into one response:

matching symbols
source location
direct callers
direct callees
tests
upstream impact
package context
deeper call relationships when requested

There are compact and deep modes.

This is deliberately not semantic RAG.

GoGraph does not pretend that it “understands” a natural-language question. It tokenizes the query deterministically, finds structural candidates, and reports how the selection was made.

If a symbol is ambiguous, it exposes the ambiguity instead of silently picking one.

That is an important design rule throughout the newer versions of GoGraph:

Uncertainty should be data, not something hidden by the tool.

From Repository Analysis to Change Analysis

The original plan idea answered:

What could be affected if I modify this symbol?

That is useful before editing.

But after an agent has changed the repository, the more interesting question is:

What did I actually change, and what does that change affect?

GoGraph now performs declaration-level change analysis against Git references and the working tree.

It distinguishes things such as:

edited declarations
added declarations
removed declarations
excluded declarations
changes that cannot be evaluated reliably

Untracked Go files are included when looking at working-tree changes.

This also avoids a surprisingly dangerous failure mode.

Imagine the agent deletes a function.

Looking only at the current graph cannot tell you who called the deleted function, because the function no longer exists.

Change analysis therefore needs historical evidence from the baseline rather than pretending the current graph contains enough information.

When GoGraph does not have enough evidence to calculate an impact safely, newer versions prefer to report that the evaluation is incomplete rather than returning an empty impact set.

For AI tooling, “I cannot prove this” is much safer than “nothing is affected.”

Graph Freshness Became a First-Class Concept

Another thing I underestimated in the original version was graph freshness.

A perfectly accurate graph of yesterday’s checkout is still the wrong answer.

GoGraph now tracks graph state explicitly.

Results can distinguish:

persisted vs. in-memory graph
current vs. stale graph
complete vs. partial parsing
AST vs. precise vs. precision-fallback analysis

MCP can refresh stale graphs automatically.

If precise enrichment fails but AST analysis succeeds, GoGraph can return the fresh AST result while explicitly saying that precise analysis failed.

If refreshing itself fails, it can retain the last trusted graph while exposing that it is stale.

The important part is that these states are not collapsed into one vague “success.”

For an AI agent, provenance matters.

There is a substantial difference between:

No callers found.

and:

No callers found.
Graph: current.
Analysis: precise.
Parsing: complete.

There is an even larger difference between that and:

No callers found.
Graph: stale.
Analysis: AST fallback.

The model should be allowed to reason differently about those answers.

Large Results Are Now Explicitly Bounded

Token efficiency was the original reason I created GoGraph, so there is an obvious irony if a structural query returns a 200 KB JSON response.

Newer GoGraph query APIs therefore put considerably more effort into bounded output.

Large result sets use deterministic pagination and expose information such as:

total
returned
truncated
next_cursor

The cursor is tied to the graph snapshot and query selection, so it cannot silently continue over a different graph after the repository changes.

MCP output also has an explicit response-size budget.

This is not merely an API optimization.

A tool built for LLMs needs to consider context consumption as part of its interface design.

Traditional developer tooling often assumes:

Returning more information is better.

Agent tooling often has the opposite requirement:

Return the smallest amount of information that preserves the evidence required for the decision.

Better Test Reasoning

Test discovery has also moved beyond simply asking whether a symbol name appears in a _test.go file.

GoGraph can now trace tests transitively through call relationships and distinguish exact test coverage paths from possible ones.

This becomes useful with architectures where a test reaches the target through several layers:

TestCreateUser
    -> handler
        -> service
            -> repository
                -> Save

Router callbacks and other intermediary functions can participate in that attribution.

Interface-backed test doubles are also important.

GoGraph’s typed test analysis can recognize cases where a test assigns a concrete fake or mock to an interface and prove the resulting call target when the type information allows it.

That makes commands such as tests and untested much more useful as structural evidence for coding agents.

It still does not mean “this code is correctly tested.”

That requires running the tests.

It means something narrower and more defensible:

These tests have a statically observable relationship to this declaration.

SQL Became Structured Evidence

SQL started as another useful static extraction target.

It has since become a more structured query system.

GoGraph can classify statically resolvable PostgreSQL statements and expose information such as:

operation
read/write access
referenced tables
access per table
source location
module
test/production origin

It understands more than literal strings.

Statically provable local constants, variables, assignments, and bounded concatenations can also participate in SQL resolution.

Dynamic SQL is intentionally not presented as if it were fully known.

The result is useful for questions such as:

Which code writes the oauth_clients table?

or:

Which production paths execute DELETE statements?

Again, the goal is not to replace a SQL parser, database audit system, or runtime tracing.

It is to give an agent a useful static census of evidence that exists in the repository.

HTTP Relationships Also Became More Precise

Route extraction existed in the original version, but HTTP reasoning has expanded.

GoGraph now distinguishes constructing an HTTP request from actually proving that the request is dispatched.

It can preserve statically known URL bases and suffixes.

More importantly, this becomes useful in the workspace model.

A repository can declare mappings between outbound HTTP client authorities and another repository in the same workspace.

That allows GoGraph to represent a relationship such as:

frontend-api
    -> HTTP request
        -> identity-service
            -> POST /users
                -> CreateUser handler

without inventing relationships from runtime environment variables or guessed hostnames.

GoGraph Can Now Analyze a Workspace

This is probably the biggest conceptual expansion since the original article.

Modern systems are often not one Go repository.

You may have:

identity-service/
agent-service/
gateway/
shared-lib/

Each repository has its own graph.

GoGraph can now build a workspace overlay across them.

The individual repository graphs remain independent. The workspace adds explicitly resolved relationships between them.

These can include cross-repository Go relationships and configured HTTP relationships.

The workspace can then answer questions such as:

What path connects this gateway handler
to this identity-service function?

or:

What repositories may be affected by this change?

There is also a separate read-only workspace MCP server exposing:

gograph_workspace_status
gograph_workspace_query
gograph_workspace_path
gograph_workspace_impact

This matters because the “whole codebase” visible to an AI agent is increasingly not the same thing as a Git repository.

The useful unit is often the engineering workspace.

Go Build Configuration Is Part of the Graph

Another source of false confidence is pretending that a Go repository has one universal structure.

It often does not.

Build tags, GOOS, GOARCH, GOFLAGS, cgo, go.work, generated files, and module selection can all change which source files constitute the program.

GoGraph now records the effective build selection used to construct the graph.

Explicit build tags are supported.

If the environment used to query a persisted graph no longer matches the environment used to build it, the graph can be considered stale rather than silently mixing incompatible views of the program.

That is another example of something which is easy to ignore in a developer convenience tool but important in an evidence tool.

Local Does Not Automatically Mean Safe

The original article emphasized that GoGraph runs locally.

That remains true.

But over time I became much more conservative about what “local static analysis” should be allowed to touch.

The current code performs extensive path and source confinement checks.

Among other things, it treats Go build inputs, module/workspace metadata, graph artifacts, and generated files carefully around symbolic links and repository boundaries.

The goal is simple:

Asking an AI agent to inspect an untrusted repository should not casually turn a static-analysis request into arbitrary traversal outside the intended source tree.

Go tooling itself can legitimately access module caches, proxies, and toolchains, so the boundary cannot simply be “never touch anything outside the repository.”

Instead, GoGraph tries to distinguish repository-controlled source authority from legitimate Go dependency resolution.

This security work is considerably less visible than a new query command, but I now consider it part of the core design.

MCP Is No Longer Just a Wrapper Around CLI Output

MCP was already present in the original version.

Its role has expanded.

The project MCP server now exposes most of GoGraph’s repository analysis capabilities directly, with CLI and MCP generally sharing the same underlying result contracts.

That prevents an unfortunate architecture where:

CLI implementation
       +
separate MCP implementation

slowly develops different semantics.

The MCP server can also expose its own version and analysis capabilities, which matters because restarting an MCP process is necessary after installing a newer GoGraph binary. An already-running process does not magically inherit the new tool schema.

The server still runs locally over stdio.

There is no hosted GoGraph service receiving the repository.

What Has Not Changed

Despite all of these additions, there are several things I deliberately do not want GoGraph to become.

It is not an AI model.

It does not decide what code should be written.

It does not replace go test.

It does not replace the compiler.

It does not replace runtime tracing.

It does not replace semantic code search.

And it should not pretend static analysis can prove runtime behavior that static analysis cannot see.

I increasingly think the useful division of labor looks like this:

LLM

reasoning
interpretation
implementation

Semantic search / grep

discovery
text
configuration
documentation

GoGraph

structural evidence
relationships
impact
provenance
uncertainty

Go compiler / tests

executable verification

These tools complement each other.

The Larger Lesson

When I wrote the first article, I described the problem mostly as a context-window problem.

I still think that is true, but I would phrase it slightly differently now.

The scarce resource is not simply tokens.

It is reliable context.

Giving an agent 50,000 lines of source code is context.

Giving it this:

CreateUser
  exact caller:
    POST /api/v1/users -> UsersHandler.Create
  exact dependency:
    UserRepository.Insert
  database:
    INSERT -> users
  attributed tests:
    TestCreateUser
    TestCreateUserDuplicate
  graph:
    current
    precise
    complete

is also context.

But the second form has already converted a large amount of syntax into a much smaller set of claims.

That is where I now see GoGraph fitting.

It is not trying to make the LLM smarter.

It is trying to reduce how much of the LLM’s intelligence has to be spent rediscovering facts that static analysis can provide deterministically.

The original goal was to give AI coding agents a map.

The current goal is slightly more demanding:

Give them evidence, identify where that evidence came from, distinguish certainty from possibility, and say when the evidence is incomplete.

For coding agents operating on large Go systems, I think that is a much more useful foundation.

GoGraph on GitHub: https://github.com/ozgurcd/gograph

Fighting Build-System Complexity: Alex Voste on Systems Programming, Performance and ForgeZero

Fri, 28 Aug 2026 12:28:22 +0000

From Systems Engineering to ForgeZero: Alex Voste on Performance, Build Systems, Assembly and the Fight Against Overhead

Developer Stories | CoderLegion

Meet Alex Voste, a Canada-based systems-focused developer working across C, Go, x86_64 Assembly, NASM, FASM, C++, Linux, performance optimization, and developer tooling.

Alex describes himself as a network systems engineer and is currently building ForgeZero, a hardened cross-platform build toolchain for C and Assembly developers.

His approach to software is strongly shaped by a fascination with what happens underneath the abstractions — from memory and computer architecture to compilers, build systems, and raw execution speed.

In this Developer Story, Alex shares how he moved from PHP and Java toward systems engineering, why he decided to build ForgeZero, his philosophy around performance and complexity, what he thinks modern build systems get wrong, and why he believes developers working close to the hardware will need strong fundamentals even in an increasingly AI-driven world.

1. From Systems Engineering to ForgeZero

How did you get into systems engineering and what eventually led you to building ForgeZero?

Alex:

I often describe myself as a network systems engineer, but let's be clear, that wasn't a title I woke up one morning and slapped on my LinkedIn. It took years of grinding through the trenches to actually earn it.

I started way back with PHP and web development, then moved into Java, doing the usual backend work. Honestly, it got boring fast. I was building the same conventional stuff everyone else was, shipping the same CRUD, wiring the same frameworks, and calling it engineering when really it was just assembly-line work with better naming conventions.

I wanted to go deeper: how programming languages actually work under the hood, how systems manage memory, or how my phone quietly phones home to corporate servers whether I asked it to or not.

Building a custom build tool wasn't some boardroom decision. It started years ago as a passion project between me and a friend.

We were two enthusiasts trying to write our own operating system in Assembly from scratch, controlling literally everything down to the bit.

Tools like Make or CMake ran completely against that philosophy. We didn't want heavy, opaque black boxes making decisions on our behalf that we never signed off on.

So I built my own toolchain, first in dependency-free Node.js, and later rebuilt entirely in Go, because at some point you get tired of fighting the tool instead of the actual problem.

2. The Problem With Modern Build Systems

What problem do you think modern build systems have, and what is ForgeZero trying to do differently?

Alex:

I firmly believe most modern build systems, and honestly most software in general, run far too many redundant operations that nobody actually needs.

They try to cover every edge case and every platform under the sun simultaneously, even when nobody asked, and you end up paying for that indecision in CPU cycles you never approved spending.

ForgeZero's philosophy is heavily inspired by Gentoo and Linux From Scratch (LFS).

A build toolchain should do exactly what the developer explicitly asks it to do, nothing more.

No hidden magic, no unnecessary overhead, zero wasted cycles.

If I didn't type it, it shouldn't be running.

That principle sits at the heart of how I think about build tooling.

3. Why Build Another Build System?

People often ask why another build system is necessary. Why did you decide to build ForgeZero instead of using existing solutions?

Alex:

People ask me all the time: why reinvent the wheel?

Honestly, I don't see ForgeZero as just another wheel.

It's more like a wheel with a twin-turbo engine bolted on, built by someone who was personally offended by how slow the old wheel was.

The codebase is lean, sitting around 42k+ lines of clean code, with no dead weight padding out a changelog just to look impressive.

I originally built it purely to save my own time.

But somewhere around the third cup of coffee at 3 AM, inspiration hits, and you start bolting on optimizations you never planned at 9 PM.

My motivation was simple: I had a clear architectural idea for how build orchestration could be blazingly fast, and I wasn't going to sit around waiting for someone else to get to it.

When I benchmarked it against real-world projects, ForgeZero came out multiple times faster than the existing solutions.

My goal is to give developers what they actually care about:

raw speed
intelligent caching
real security
total manual control

Not a dashboard cheerfully telling them everything's fine while it quietly isn't.

4. Why Go and Assembly?

Why did you choose Go as the foundation for ForgeZero, and where does Assembly fit into the project?

Alex:

I chose Go as the foundation because it strikes a rare balance between simplicity and safety.

Write pure C or Assembly for everything, and it's incredibly easy to leave behind a subtle memory bug or race condition you'll be debugging at 4 AM, hating your past self with real, focused intensity.

Go gives me near-C performance while sparing me the catastrophic runtime failures I no longer have the patience to hunt at that hour.

That said, I do use Assembly in ForgeZero, specifically Plan 9 Assembly, on the performance-critical paths.

That's where a huge chunk of our raw execution speed comes from, and no amount of clever Go abstraction replaces hand-placed instructions where it actually counts.

When it's a choice between an optimization that adds complexity or keeping things simple for safety's sake, I'll take the optimization almost every time.

ForgeZero has a fair amount of low-level, high-risk Go code where we bypass standard allocations entirely.

As long as I keep tight control over those boundaries, the performance gains are massive, and I'd rather own that risk deliberately than inherit someone else's by accident.

5. Where Does the Performance Difference Come From?

ForgeZero reportedly performs significantly faster than some existing build tools. What is behind that difference?

Alex:

If you look at the benchmarks where ForgeZero significantly outperforms tools like Ninja on large task sets, the secret isn't some clever trick hiding in a corner.

It's simplicity, plain and unglamorous.

And I know that answer disappoints people hunting for a silver bullet.

When your architecture isn't burning cycles managing legacy abstractions, allocation overhead, or bloated state graphs nobody asked it to maintain, execution ends up blindingly fast almost by default.

We do fewer things, but we do them at the bare-metal limit, on purpose, every single time.

6. Building for Low-Level Developers

What do you think existing developer tooling gets wrong about low-level developers?

Alex:

What existing tooling gets wrong about low-level developers is assuming we want convenience over control.

Most modern dev tools are built around a web-dev mindset: hide the complexity, abstract the system, install 500 MB of dependencies for something that should take twenty lines, and pretend the hardware isn't even there.

Systems engineers, C programmers, Assembly devs, we don't want black boxes.

We want to see the hardware.

We want toolchains that stay out of our way, don't force opinionated directory structures on us like we're kids who need supervision, and don't burn cycles on telemetry or bloated config parsers nobody reads.

Existing tools try to be everything for everyone and end up being genuinely excellent at nothing.

Low-level devs just want a tool that gets out of the way, respects the hardware, and executes instantly.

Full stop.

7. Open Source and Building in Public

What role does open source play in your approach to software development?

Alex:

My core philosophy has always centered on building free, open-source software.

That doesn't mean I never build proprietary products that generate revenue, but when it comes to fundamental tooling, I'd rather keep it open for the community, because gatekeeping a build tool behind a paywall feels beneath the entire point of building one.

For instance, I'm currently working on a confidential AI project applied to medical engineering, more on that down the road.

Building in public keeps your architecture honest, because anyone can audit your code, and nothing sharpens discipline quite like knowing a stranger might read your worst commit at 2 AM and judge you for it, correctly.

8. Performance vs. Complexity

How do you decide when a performance optimization is worth the additional complexity?

Alex:

In theory, there's a point where chasing performance stops being worth the engineering complexity.

But if I'm being completely honest about my own process, I don't always respect that limit, and I'm not going to pretend otherwise just to sound balanced in an interview.

I have a relentless drive to push code until it literally cannot run any faster.

As a general rule though, performance optimizations are worth the complexity when they scale linearly with user productivity.

If an optimization saves a developer five seconds on every single build loop, that's hours of focus reclaimed across a real team every week.

But if an optimization makes a codebase unmaintainable just to shave two microseconds off an idle thread nobody's even timing, you've crossed into vanity engineering.

Vanity engineering is just ego wearing a lab coat.

Balance comes down to measuring real-world impact over synthetic vanity, every time, no exceptions.

9. AI and Low-Level Engineering

How do you think AI will affect low-level software engineering?

Alex:

My stance on this is firm: AI will never fully master low-level systems engineering, and I'll happily die on this hill.

I might sound provocative, but based on my own experience, LLMs operate at a noticeably lower level of competence in systems programming compared to high-level web development.

Low-level engineering demands deep spatial reasoning, hardware awareness, and architectural intuition that isn't sitting anywhere in a training set in a usable form.

I actually tested this.

I tried using an AI assistant to help build a low-level, cryptographically secure messenger.

I wasn't asking it to write AES-256-GCM from scratch, I just wanted help with a simple client-server network implementation.

It failed miserably.

I spent days fighting hallucinations and sloppy memory handling before scrapping the AI output entirely and writing the whole thing myself, in a fraction of the time it cost me babysitting the assistant.

AI can fetch docs, summarize a man page, and sound confident doing it.

But it can't reason about bare-metal constraints the way someone who's actually been burned by them can.

For low-level devs, understanding C, Assembly, and computer architecture is only going to matter more, not less, because someone still has to fix the broken code AI generates, and that someone needs to actually know what they're looking at.

10. What Comes Next for ForgeZero?

Where do you want to take ForgeZero next?

Alex:

My immediate goal is assembling a core team of like-minded developers, engineers who are ready to break things, innovate, and move fast without asking permission for every single decision.

I want ForgeZero to be completely free, hyper-fast, and genuinely intelligent, possibly integrating lightweight, targeted AI for build-graph optimization down the line, used smartly and sparingly, not bolted on as a marketing checkbox.

I'm always inviting developers to jump into the repo and build this with me.

No corporate bureaucracy, no meetings that could've been a commit message, just pure engineering.

11. The Engineer Behind the Optimization

Where does your obsession with performance and removing unnecessary complexity come from?

Alex:

Honestly, a deep-seated refusal to accept artificial limits, the ones nobody ever actually proved necessary, just inherited from whoever came before.

Most developers look at a slow tool or a bloated framework and think, well, I guess that's just how software is now, and move on with their day.

I can't do that.

When I see an idle loop burning CPU cycles, or a build tool taking 30 seconds to parse a dependency tree that should take 50 milliseconds, it feels like a personal insult.

Call it perfectionism, call it an obsession with zero overhead.

I genuinely love taking a bloated process, stripping away the noise, and watching it run at the absolute limit of the hardware.

That feeling never gets old.

The day it does is probably the day I stop doing this for a living.

About Alex Voste

Alex Voste is a developer based in Canada with a focus on systems programming, performance optimization, open source, and developer tooling.

His technical interests include:

C
Go
x86_64 Assembly
NASM
FASM
C++
Linux
Node.js
Performance optimization
Linkers

Alex is currently building ForgeZero, a hardened cross-platform build toolchain for Assembly and C developers.

ForgeZero

ForgeZero brings together tools including NASM, GAS, FASM, GCC, Clang, LD, and Zig behind a unified workflow for low-level developers.

You can explore the project here:

GitHub:
https://github.com/forgezero-cli/forgezero

CoderLegion Profile:
https://coderlegion.com/user/alexvoste

Final Thoughts

Alex's story is a reminder that software development doesn't have to stop at the abstraction layer.

For some engineers, the interesting questions begin underneath it:

What is the machine actually doing?

Where are the cycles going?

Why is this process taking so long?

Which parts of the system are genuinely necessary?

And perhaps most importantly:

What happens if we remove everything that doesn't need to be there?

ForgeZero is Alex's answer to those questions — a project built around speed, control, simplicity, security, and a strong dislike of unnecessary overhead.

Whether you agree with all of Alex's opinions about modern tooling or AI, his approach highlights an important principle for developers at every level:

Understand the system underneath the abstraction.

That understanding becomes even more valuable when the tools themselves start writing the code.

Gnat - Self-Hosted Analytics

Fri, 14 Aug 2026 19:45:17 +0000

A few months back I was crawling the web for a side project and came across an analytics platform's data that had exposed users' raw IPs. It wasn't malicious, just careless. But it stuck with me: most people using these tools have no idea their visitors' data is sitting around like that.

That's the moment that pushed me to build Gnat, a self-hosted analytics tool that doesn't cut corners on privacy, but also doesn't force you into a painful setup to get it.

No third party, no phoning home

Gnat runs entirely on infrastructure you control. No third party in the loop, no API calling home anywhere, no data leaving your server. Completely free and open source.

One binary, zero bloat

Most self-hosted analytics tools make you choose: something lightweight with barely any real analysis, or something with real depth that also means Docker, a multi-service stack, and its own ops burden.

Gnat is a single Go binary. No CGO, no Docker, no multi-service stack. The dashboard is compiled straight into the executable.

tar xzf gnat-vX.Y.Z-linux-amd64.tar.gz
cd gnat-vX.Y.Z-linux-amd64
./gnat

That's the whole install.

Live demo: https://gnat-np2m.onrender.com/dashboard (password: vJzTMw0bjTtWHyNpBCPGaZqE, feel free to poke around, it's a shared demo instance so please be gentle with it)

Visit my portfolio here and see it appear on the analytics dashboard https://var-raphael.vercel.app

Real analytical depth

Pageviews and custom events via JSON POST, no per-language SDKs
Funnels, cohorts, retention curves
Auto-discovered path analysis
SQLite by default, or Postgres/MySQL if that's how you already run infrastructure
CSV, JSON, and raw SQL export, it's your data

Built for the agent era

Gnat ships with a native MCP server. Claude or any MCP-compatible agent can query your analytics directly, no separate API glue.

Where it's at

Early days, v0.1.0, and I'm actively building on it. Multi-site support, SSO/team access, and managed hosting are on the roadmap but not built yet.

Licensed under AGPLv3, free to self-host and modify for any purpose, including commercially, but if you run a modified version as a service for others, the source has to stay open under the same terms.

I'd love feedback, issues, and contributors, especially if you've felt the same Docker-and-multi-service fatigue trying to self-host analytics.

Repo: https://github.com/var-raphael/Gnat

Ninja is Slow. We Built a Build System in Go That Outperforms It by 39x on a Quarter-Million Tasks

Fri, 03 Jul 2026 13:10:46 +0000

ForgeZero 2.0: We Built a Build System 39x Faster Than Ninja

And yes, it's open source. No bullshit, just architecture.

The Problem Everyone Ignores

You've been there. Sitting at your desk, coffee getting cold, waiting for your build to finish. 10 seconds. 30 seconds. A minute.

CMake parses its DSL. Ninja forks 2,000 processes. Make thrashes the disk. GNU Autotools exists, and everyone pretends not to notice.

This isn't a feature gap. This is architectural malpractice.

Every major build system was designed in an era when parallelism meant "spawn processes." That's it. No thought given to the actual cost—fork syscalls, context switching, memory duplication, I/O bottlenecks.

We decided to fix it properly.

What ForgeZero Actually Is

ForgeZero is a cross-platform build system for C, C++, Objective-C, and Assembly. Written in Go. Single binary. No configuration files needed.

Point it at a directory:

fz build -o binary

It detects your source files, selects compilers (GCC, Clang, Zig), picks assemblers (NASM, GAS, FASM, or embedded), and outputs production-ready binaries, libraries, or ISO images.

That's literally it.

No Makefile. No CMakeLists.txt. No autotools scripts. One command. Full parallelism. Reproducible builds by default.

Repository: https://github.com/forgezero-cli/forgezero
License: GPLv3 (fully open source)

The Benchmark That Broke Ninja's Narrative

Real project. 2,000 object files. 1,000 .c source files. Real hardware.

ForgeZero:  258 ms  (User: 348ms, System: 520ms)
Ninja:      10.1 s  (User: 73.9s, System: 47.8s)

Speedup: 39.2x ✓

This isn't synthetic. This isn't a contrived test case. This is what happens when you link 2,000 real object files on a real codebase.

The gap grows with scale:

File Count	ForgeZero	Ninja	Speedup
1,000	~85ms	~2.7s	32x
2,000	~258ms	~10.1s	39x
10,000	~1.2s	~50s	~42x

Ninja's overhead scales linearly with file count. ForgeZero's scales logarithmically. The larger your codebase, the more you win.

Watch the actual benchmark: https://t.me/wienton/176

Why This Demolishes Every Competitor

1. Architecture: One Process, Infinite Goroutines

Traditional systems:

foreach file:
  fork() → new process
  compile
  wait for completion
  write .o to disk
  read .o back for linking

ForgeZero:

spawn N goroutines (microseconds, not milliseconds)
all 2000 files compile in parallel
all objects stay in memory
linker reads from memory arena
zero context switching overhead

The difference: Goroutine creation = microseconds. Process fork = milliseconds. At 2,000 files, you're talking about 1-2 seconds saved just on process overhead.

2. Zero Allocations in Hot Paths

This is the part other build systems don't even think about.

BenchmarkLinkerHotPath:  0 allocs/op, 0 B/op
BenchmarkCodegenHotPath: 0 allocs/op, 0 B/op
BenchmarkHashBLAKE3:     0 allocs/op, 0 B/op

No garbage collection pauses. No "stop-the-world" events. Deterministic latency like C or Rust.

Achieved through:

Pre-allocated arenas for intermediate objects
Stack buffers for I/O operations
sync.Pool for temporary structures
Zero make(), append(), or new() in critical sections

When you're linking thousands of files, GC pauses compound. We eliminated them entirely.

3. Memory-Resident Object Cache

Ninja writes every .o file to disk, then reads it back. Disk I/O at SSD speeds is 500 MB/sec.

ForgeZero keeps objects in memory: 10+ GB/sec throughput.

On a 2000-file project, this alone saves 200-300ms.

4. BLAKE3 Instead of SHA-256

Caching depends on file hashes. SHA-256 is cryptographically solid but slow.

BLAKE3 is:

7x faster than SHA-256
Parallel (SIMD accelerated)
Cryptographically modern

On 2000 files: SHA-256 (~500ms) vs BLAKE3 (~70ms). That's 430ms saved per rebuild.

5. Custom Lock-Free Scheduler

ForgeZero doesn't rely on the OS scheduler. It implements its own:

Mutex, Semaphore, WaitGroup (no external dependencies)
Lock-free ring buffer for task queues (CAS atomics)
Worker pool with goroutine reuse
Atomic counters (no mutex contention)

Even under load, zero contention. Maximum throughput.

What's New in ForgeZero 2.0 (v5.3.0)

Embedded x86 Assembler

NASM is gone. ForgeZero now includes a native Intel-syntax assembler that generates correct ELF64 object files.

One dependency eliminated
Works on all platforms (Linux, Windows, macOS)
Same behavior everywhere

ISO Image Generation

fz build -iso -iso-out kernel.iso
qemu-system-x86_64 -cdrom kernel.iso

For kernel and firmware developers: no more mkisofs scripts. One flag. Bootable ISO. Done.

Support for -iso-hybrid (BIOS + UEFI).

Three Cache Modes

fz build                  # disk mode (default, persistent)
fz build -cache=ram       # memory mode (CI/CD, ephemeral envs)
fz build -cache=off       # no cache

Perfect for Docker containers where disk is slow or ephemeral.

Inline Bash Scripts

scripts:
  - bash: echo "Building..."
  - bash: ./configure --prefix=/usr
  - bash: make install

If no shell exists, uses embedded minimal runner (cd, export, direct binary calls).

Rollback Support

fz --rollback              # Revert to previous version
fz --rollback-to v5.2.0    # Revert to specific version

Production-grade versioning. If something breaks, you recover in seconds.

Rewritten Scheduler

Removed external workerpool dependency. Built custom with:

Better error aggregation
Context-based cancellation
Graceful shutdown
Full race condition safety

Rewritten Config System

Low-allocation merging (no unnecessary copies)
Parallel config loading
Clear merge semantics (strings override, slices deduplicate, maps merge)
Safe defaults with validation

Cross-Platform Reality

Single codebase. Three platforms. Identical behavior.

Linux:

Direct syscalls via golang.org/x/sys/unix
SYS_OPENAT, SYS_UNLINKAT
No libc

Windows:

Native implementation via golang.org/x/sys/windows
CreateFile, ReadFile, WriteFile APIs
Retry logic for file locks

macOS:

Full Darwin syscall support
Identical behavior to Linux

VFS Layer abstracts all OS differences:

Path/separator normalization
TOCTOU attack prevention
Symlink boundary enforcement (security by default)

Built-In Security (Not Bolted On)

fz audit — SAST Scanner

fz audit              # Scan for all issues
fz audit --strict     # Strict mode

Detects:

Secrets (AWS keys, GitHub tokens, API keys)
Dangerous patterns (gets, sprintf without bounds, alloca in loops)
License violations (GPL/AGPL in proprietary projects)
Known CVEs in dependencies

fz sbom — Software Bill of Materials

fz sbom --output sbom.xml

CycloneDX format with BLAKE3 hashes for every component. Essential for aerospace, medical, and fintech systems.

fz verify — Source Integrity

fz verify --manifest .fz.manifest

Checks every file against BLAKE3 manifest. Detects corruption and supply chain attacks.

--reproducible — Bit-for-Bit Reproducibility

fz build --reproducible

Two builds of identical code produce identical binaries (down to the last byte):

Build ID suppressed
Timestamps zeroed
Paths normalized
Order deterministic

Verifiable that no one modified your source.

fz doctor — Environment Diagnostics

fz doctor

Checks:

Compiler availability and versions
File access permissions
Platform integrity
Required dependencies

Human-readable report of what works and what doesn't.

Supported Everything

Category	Details
Languages	C, C++, Objective-C, Assembly (NASM/GAS/FASM), Gloria (custom bare-metal language)
Output	ELF, PE, Mach-O, static libraries, shared libraries, flat binaries, ISO images
Cross-Compilation	ARM (32/64), RISC-V, WebAssembly, Windows, full support via Zig toolchain
Tools	`-compile-commands` (LSP), `-watch` (file monitoring), `-shell` (REPL), `-bench` (profiling), `-debug` (DWARF symbols)
Advanced	Bare-metal linking, custom linker scripts, freestanding environments, BIOS+UEFI support

Package Manager (fz pm)

fz pm add <repo>[@version]    # Add from Git
fz pm remove <package>         # Remove
fz pm list                     # List installed
fz pm catalog                  # Browse official catalog
fz pm search <query>           # Search
fz pm install <name>           # Install with BLAKE3 verification

All packages verified with BLAKE3 before installation. No npm dependency hell.

The Numbers Don't Lie

976 commits in 2 months (16 commits/day—this is sprint-grade work)
42,048 lines of code (32,275 Go, rest tests + docs)
234 Go files
90%+ test coverage on critical packages
0 allocations in hot paths (benchmarked)
100% golangci-lint in strict mode
Passes all -race checks (no data races)
Works on Linux, Windows, macOS with zero code changes

This is not fantasy. This is production-grade code.

Comparison: The Reality Check

Feature	Make	Ninja	CMake	ForgeZero
Config files	Yes	Yes	Yes	No
Caching	No	Limited	No	3 modes
Parallelism	Processes	Processes	Processes	Goroutines
Zero-alloc paths	No	No	No	Yes
Embedded assembler	No	No	No	Yes
ISO images	No	No	No	Yes
Package manager	No	No	No	Yes
SAST/SBOM	No	No	No	Yes
Cross-compilation	Limited	Limited	Limited	Full
Speed	Baseline	Fast	Medium	39x Ninja
Windows native	Limited	Limited	Yes	Yes
Rollback support	No	No	No	Yes
Reproducible builds	No	No	No	Yes

One system dominates every dimension.

System Requirements

OS: Linux, Windows (native or WSL2), macOS
Architecture: amd64, arm64
Optional: GCC/Clang (C/C++), Zig (cross-toolchain), Git (package manager)
For ISO: xorriso (separate installation)

Everything else is embedded in a single binary.

Why This Matters: The Reality

Speed Changes Workflow

Before: 10 seconds per rebuild = context lost
After:  250 milliseconds per rebuild = never interrupt flow

This isn't productivity theater. This is fundamental work process improvement.

On a 50-engineer team, if each engineer rebuilds 50 times per day:

Ninja:      10s × 50 builds × 50 engineers = 41,666 seconds wasted
ForgeZero:  0.25s × 50 builds × 50 engineers = 1,041 seconds wasted

Saved: 40,625 seconds/day = 11.3 person-hours/day

That's literally one full-time engineer's output, reclaimed.

No Config = No Errors

CMakeLists.txt, Makefile, autotools—these are programming languages with their own syntax, semantics, and pitfalls.

ForgeZero needs zero configuration to work. YAML if you want customization. That's it.

New developers don't spend a day figuring out the build system. They fz build. Done.

Systems Work Is Irreplaceable

This tool exists because systems programming is fundamentally different. You can't CMake your way out of bare-metal development.

Kernel developers need embedded assembly → we built it in
Firmware developers need ISO images → integrated
Security-critical projects need SBOM and reproducible builds → bundled
Embedded devs need cross-compilation → fully supported

We're not trying to replace Gradle or Maven. We're building the right tool for systems work.

The Roadmap

We're not done:

Linux Kbuild support for kernel compilation
Enhanced IDE integration (VSCode, CLion)
Gloria language expansion (custom systems language)
Further performance optimization (targeting 50x+ speedup)
Additional architecture support (PowerPC, MIPS)

This is a living project. 976 commits in 2 months. Not a one-off. Not a side project. Real engineering work.

Who This Is For

You're a Systems Programmer

Building kernels, bootloaders, or firmware
Need deterministic, reproducible builds
Want security integrated, not bolted on
Tired of Makefile spaghetti

This is for you.

You Manage a Build Infrastructure

Your CI/CD pipeline is 60% waiting for builds
You want to scale without renting more cloud resources
You need reproducible, verifiable builds

This saves money and time.

You Care About Simplicity

You believe configuration is a source of bugs
You want tools that work zero-config and scale up
You respect your developers' time

This respects your choices.

Get Started

# Linux/macOS
curl -sSL https://raw.githubusercontent.com/forgezero-cli/ForgeZero/main/install.sh | bash

# First build
fz build -o my_program

# Watch the speed difference
touch src/main.c && fz build -o my_program

Follow updates: https://t.me/wienton/176

The Statement

ForgeZero isn't an improvement on Ninja. It's not an optimization of Make. It's a complete rewrite of what a build system should be, informed by:

Modern hardware (multi-core, SIMD, large memory)
Modern languages (Go, with its goroutines and concurrency primitives)
Real systems work (assembly, bare-metal, cross-compilation)
Security best practices (reproducible builds, SBOM, SAST)

This is a challenge to the industry: Slow builds aren't inevitable. They're architectural choices. Fix the architecture, and speed fixes itself.

If you're tired of waiting for builds. If you're exhausted by CMake configuration. If you just want to code, not configure—ForgeZero is for you.

The Details

Author: Alex Voste

Repository: https://github.com/forgezero-cli/forgezero

Latest Release: v5.3.0

License: GPLv3 (fully open source, fully free)

Fast builds aren't a luxury. They're an engineering necessity. ForgeZero delivers.

Make it so.

Why I chose a Tiered Caching strategy for PixoraCloud.

Wed, 24 Jun 2026 20:02:29 +0000

I’m deep in the lab engineering the Pixora transformation engine (using libvips + Go), and I had to make a call on caching: Redis vs. Local Disk.
Common mistake: Using Redis for everything.
Reality: RAM is fast, but RAM is expensive. If I cache every transformed image in Redis, the server bill will bankrupt the project before we even hit Beta.

My Solution: The Two-Tiered Architecture.
L1 (Redis): Stores only the "Hot" assets (the most requested thumbnails/avatars). This keeps our sub-120ms latency promise for 90% of requests.
L2 (Disk/Object Storage): Stores the processed, high-res versions. If it's not in Redis, we grab it here.
The Trade-off:
Redis gives us the raw speed to hit sub-50ms lookups.
Disk storage keeps our operating costs lean so we can pass those savings to you.
We aren't just building a CDN; we’re building infrastructure that has to survive in a low-bandwidth, high-latency market.
Building in public is all about these trade-offs. What would you have chosen? Let’s talk architecture in the comments. 👇

Join waitlist https://pixoracloud.pxxl.click

Go types explained: the foundation you need before writing HTTP handlers

Mon, 22 Jun 2026 14:44:03 +0000

A quick introduction to Go types

According to https://go.dev/ref/spec#Types, in Go, a type specifies a set of values, along with operations and methods specific to those values.

This is something fundamental about Go: you can define your own types based on existing ones, and those types can have methods attached to them.

You've probably seen this with structs:

// A struct type — groups fields together
type User struct {
    Name  string
    Email string
}

// A method attached to the User type
func (u User) Greet() string {
    return "Hello, " + u.Name
}

But Go lets you do the same thing with any type, including functions.

Function types

In Go, functions are values. You can assign them to variables, pass them as arguments, and — most importantly here, define a named type based on a function signature:

// This defines a new type called "Greeter"
// whose underlying type is a function that takes a string and returns a string.
type Greeter func(name string) string

Now Greeter is a type, just like int or string or User. Any function with the right signature (func(string) string) is automatically a Greeter.

// This function matches the Greeter signature
func sayHello(name string) string {
    return "Hello, " + name
}

// So we can assign it to a Greeter variable
var g Greeter = sayHello

fmt.Println(g("Alice")) // Hello, Alice

Attaching methods to a function type

Here's where it gets interesting. Because Greeter is now a named type, you can attach methods to it, exactly like you would with a struct:

// A method on a function type — this is valid Go
func (g Greeter) Shout(name string) string {
    return strings.ToUpper(g(name)) // call the function, then shout it
}

fmt.Println(g.Shout("Alice")) // HELLO, ALICE

This might look strange at first. A function with a method? But it makes perfect sense in Go. Greeter is just a type, and any type can have methods.

Why this matters for HTTP handlers

Now that you understand function types, let's look at how Go's HTTP package uses this exact pattern to make your life easier.

Go's HTTP package has two things that are easy to confuse at first: http.Handler and http.HandlerFunc. They sound almost identical, but they play different roles: one is an interface, and one is a type.

http.Handler — the interface

An HTTP handler in GO is an object or function responsible for processing an incoming HTTP request and constructing an HTTP response.

http.Handler is the interface that represents anything that can handle an HTTP request. It has exactly one method:

// http.Handler is an interface — a contract.
// It says: "I don't care what you are.
// As long as you have a ServeHTTP method, you can handle HTTP requests."
type Handler interface {
    ServeHTTP(ResponseWriter, *Request)
}

http.ResponseWriter: An interface used to construct and send the HTTP response (setting headers, status codes, and writing the body).
*http.Request: A pointer to a struct containing all incoming data (headers, query parameters, URL path, and request body).

So, to be recognized as a handler, a type must implement the http.Handler interface by defining a ServeHTTP.

This is what Go's HTTP server actually works with internally. When you call http.ListenAndServe, the second argument must be an http.Handler:

// The second argument is an http.Handler —
// Go's server calls ServeHTTP on it for every incoming request.
http.ListenAndServe(":8080", myHandler)

Any type that has a ServeHTTP method satisfies this interface automatically. A struct, a function type, anything, as long as it has that one method.

http.HandlerFunc — the type

Here's the problem: writing a full struct with a ServeHTTP method for every single handler in your app is verbose. Most of the time, you just want to write a plain function:

// This is clean and simple, just a function.
// But it's NOT an http.Handler because it has no ServeHTTP method.
func greetUser(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintln(w, "Hello!")
}

This function can't be passed to http.ListenAndServe directly, it's not an http.Handler. It has no ServeHTTP method.

This is exactly the problem http.HandlerFunc solves. It's a named function type with a ServeHTTP method attached, which makes it an http.Handler:

// HandlerFunc is a named type based on a function signature.
// Any function that matches func(ResponseWriter, *Request)
// is automatically compatible with this type.
type HandlerFunc func(ResponseWriter, *Request)

// ServeHTTP is attached to HandlerFunc.
// It just calls the function itself — f is the function, so f(w, r) runs it.
// This single method is what makes HandlerFunc satisfy http.Handler.
func (f HandlerFunc) ServeHTTP(w ResponseWriter, r *Request) {
    f(w, r)
}

Now Go can convert your plain function into an http.HandlerFunc, which has ServeHTTP, which satisfies http.Handler.

You can imagine that this is what Go does under the hood:

var fn http.HandlerFunc = greetUser  // convert the function to HandlerFunc
var h  http.Handler    = fn          // HandlerFunc satisfies http.Handler

But, in practice, you never write these steps manually; you use the http.HandleFunc function.

http.HandleFunc

// Registers the "/hello" route on the default mux.
// http.HandleFunc converts greetUser to HandlerFunc internally —
// you never see that conversion happen.
http.HandleFunc("/hello", greetUser)

http.HandleFunc register a route on the default server mux. It takes a path and a handler function, converts the function to a HandlerFunc internally, and registers it.

http.HandleFunc actually uses http.HandlerFunc internally, it's just hiding it from you:

// This is roughly what http.HandleFunc does under the hood:
func HandleFunc(pattern string, handler func(ResponseWriter, *Request)) {
    // converts your function to HandlerFunc, then registers it
    DefaultServeMux.Handle(pattern, HandlerFunc(handler))
    //                                ^^^^^^^^^^^^^
    //                                HandlerFunc TYPE doing the conversion
}

So http.HandleFunc is convenience on top of http.HandlerFunc. When you call http.HandleFunc("/hello", greetUser), Go silently wraps greetUser in an http.HandlerFunc and registers it. You only need to use http.HandlerFunc directly when you're building something lower-level, like middleware, where you need to return an http.Handler explicitly.

Putting it all together

Here's the full picture in one example:

// A plain function — clean and simple to write
func greetUser(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintln(w, "Hello!")
}

// A struct handler — useful when you need to hold state like a DB client
type UserHandler struct {
    db *sql.DB // injected dependency
}

func (h *UserHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    // can use h.db here
    fmt.Fprintln(w, "Hello from UserHandler!")
}

func main() {
    mux := http.NewServeMux()

    // http.HandleFunc converts greetUser → HandlerFunc → Handler automatically
    mux.HandleFunc("/hello", greetUser)

    // UserHandler already has ServeHTTP — it satisfies http.Handler directly
    mux.Handle("/user", &UserHandler{db: myDB})

    // Both routes are registered on the same mux —
    // the server calls ServeHTTP on whichever one matches the request path.
    http.ListenAndServe(":8080", mux)
}

TIP: Use a plain function (via HandlerFunc) for simple handlers. Use a struct for handlers that need dependencies like a database client or a config object. The server doesn't care which one you chose — it just calls ServeHTTP.

Summary

Think of it this way:

http.Handler is the job description: "must be able to handle HTTP requests"
http.HandlerFunc is one way to fulfill that job description: "a plain function that handles HTTP requests"
Your struct with a ServeHTTP method is another way to fulfill it

The server only knows about http.Handler. It never knows whether you used a struct or a HandlerFunc — and it doesn't need to. That's the power of the interface.

Why I Still Choose Go After All These Years

Wed, 10 Jun 2026 13:38:44 +0000

Hello everyone.

I'd like to discuss a topic that has sparked endless debates among developers for years:

What programming language should you choose for a serious project?

Throughout my career, I've worked with C, Assembly, Go, and spent a considerable amount of time exploring modern languages such as Rust and C++. The more experience I gain, the more convinced I become that there is no perfect programming language. Every language has its own strengths and weaknesses.

Despite that, I deliberately chose Go as the foundation of my primary project: ForgeZero.

ForgeZero is a cross-platform build orchestration tool written in Go, with carefully optimized performance-critical components implemented in Plan 9 Assembly to minimize runtime overhead and eliminate unnecessary allocations.

At first glance, it might seem logical that after working with C and Assembly, the next step should be Rust or modern C++, since they are widely considered the future of systems programming.

Rust

Rust solves an impressive number of memory safety problems.

Its ownership model and borrow checker force developers to think about lifetimes and resource management before the code even compiles.

However, safety comes at a cost.

There are moments when it feels like the language dictates your architecture rather than the other way around. In large projects, satisfying the borrow checker can sometimes consume more time than solving the original problem itself.

Even with Rust's strict guarantees, bugs still exist. No language can eliminate every possible programming mistake.

Personally, I also find large Rust codebases relatively difficult to read. The amount of syntax and abstractions often makes understanding unfamiliar code slower than it should be.

C++

C++ is an incredibly powerful language.

Unfortunately, that power comes with enormous complexity.

Templates, metaprogramming, concepts, multiple paradigms, countless coding styles, and dozens of ways to solve the same problem can make maintaining large codebases challenging.

Sometimes reading someone else's C++ project feels less like software engineering and more like an archaeological expedition.

C

C remains one of the greatest programming languages ever created.

It provides maximum control over the system, minimal abstractions, and extremely predictable performance, making it an outstanding choice for low-level development.

The downside, however, is responsibility.

Every pointer, every allocation, and every memory access becomes your responsibility. Bugs such as use-after-free, buffer overflows, or segmentation faults can be devastating.

And perhaps even more importantly, building large software systems in C requires an enormous investment of engineering time.

Had ForgeZero been written entirely in C, both development and long-term maintenance would have been significantly more expensive.

Why Go?

Go occupies a very unique position.

It is simple enough that new contributors can understand a codebase within days, while still being powerful enough to build serious production-grade software.

Goroutines, channels, built-in concurrency, and a minimalistic syntax allow developers to focus on solving problems instead of fighting the language.

Of course, Go has its own limitations.

The runtime, garbage collector, and automatic memory management make it a poor choice for operating system kernels, drivers, or extremely low-level software.

Yet the common belief that Go cannot deliver high performance is simply incorrect.

With careful architecture, proper escape analysis, object pooling, and manual optimization of performance-critical paths, it is entirely possible to achieve nearly zero allocations where they actually matter.

That is exactly the direction ForgeZero takes.

For me, Go represents an excellent balance between development speed, maintainability, readability, and performance.

It is not perfect.

But it allows me to build complex tooling faster than most alternatives without sacrificing quality.

That is why, after all these years, I still choose Go.

Am I Betraying C?

Absolutely not.

C shaped me as a software engineer, and I still consider it one of the greatest programming languages ever designed.

In fact, one of ForgeZero's goals is to make C development easier, improving build workflows and project management for both newcomers and experienced engineers.

Go may be my primary language today, but that does not mean abandoning C.

A huge portion of modern software infrastructure still depends on it.

Operating system kernels, drivers, networking libraries, embedded software, and countless system components have been built and refined in C for decades.

Many developers now discuss Rust's introduction into the Linux kernel and the future of systems programming.

But realistically, no major company or open-source project is going to rewrite millions of lines of stable legacy C code overnight simply because a newer language exists.

Large migrations take years—sometimes decades—and happen gradually.

For that reason alone, C will remain relevant for a very long time.

And personally, I still use it whenever it is the right tool for the job.

Recently, while training a small neural network on my home machine, I encountered an interesting problem.

The hardware is far from modern: an eight-core CPU from 2014 paired with a GTX 1060 6GB (Pascal architecture). Although training was performed on the GPU through PyTorch, the CPU was still under significant thermal stress.

Instead of building a monitoring solution in Python or deploying heavyweight background services, I wrote a small daemon in C that continuously monitored CPU temperature and automatically terminated non-essential processes once critical thresholds were reached.

Could I have written the same utility in Go?

Absolutely.

But for this particular low-level task, C was simply the better tool.

No runtime, minimal dependencies, tiny resource usage, and complete control over the operating system.

That is exactly why I never claim that Go should replace C.

Quite the opposite.

I believe that Go + C + Assembly is an incredibly powerful combination.

Go excels at infrastructure, CLI applications, automation, backend services, and distributed systems.
C remains unmatched for systems programming and direct interaction with operating system internals.
Assembly is invaluable when every CPU cycle matters and maximum optimization is required.

A good engineer should choose the right tool for the problem—not the trendiest language on social media.

My Advice for Beginners

If I had to start my programming journey again, I would begin with C.

Not because it is the "best" language, but because it forces you to understand how computers actually work.

How memory is organized.

How the stack and the heap operate.

How pointers behave.

How a compiler transforms source code into assembly instructions and eventually into machine code executed by the processor.

Once those fundamentals become clear, learning Go, Rust, C++, Java, or almost any other language becomes dramatically easier.

You stop memorizing syntax and start understanding software engineering.

So my advice is simple:

Don't be afraid of low-level programming.

Even if your future career revolves around web services or cloud infrastructure, understanding what happens beneath the abstractions will make you a far stronger engineer.

Programming languages come and go.

Fundamental computer science knowledge stays with you forever.

ForgeZero v4.2.0: 2.84x Faster Than Ninja. Zero CGO. Zero Compromise.

Wed, 27 May 2026 17:09:17 +0000

We shipped v4.1.0 with a clear mandate: eliminate heap allocations from every critical path,
harden the syscall layer, and make the build engine deterministic at hardware limits.
v4.2.0 delivers on that — and then goes further.

This release drops CGO entirely, ships a native Windows syscall driver, and pushes
the assembler hot-path through SIMD rewrites and sync.Pool recycling. The result is a
build orchestrator that runs at 637 ms mean against Ninja's 1.813 s on a 1000-module
C project. That is a 2.84x lead, sustained across 10 runs with sub-35 ms range variance.

Benchmark: ForgeZero vs Ninja, 1000 C Modules

Tool	Mean	Range	Runs
fz (ForgeZero)	637.3 ms	626.6 ms — 685.5 ms	10
ninja	1.813 s	1.800 s — 1.834 s	10

2.84x faster. Consistent. Reproducible.

Hardware: Intel i5-10310U. Cold filesystem cache. No artificial throttling.
The variance on fz is 58.9 ms peak-to-peak. On ninja it is 34 ms — but starting from
nearly three times higher. ForgeZero is not only faster, it is stable.

The previous release already showed 3.25x against make -j4 at 100 modules. This holds
as the module count scales to 1000 against a purpose-built parallel tool. That is not a
benchmark trick. That is architecture.

The Big Change: CGO is Gone

v4.1.0 still carried CGO at the entrypoint and in the C plugin loader. Every build that
touched cplugin dragged in the C toolchain, broke cross-compilation, and introduced
non-determinism in the binary ABI.

v4.2.0 removes it completely.

The mechanism is GoContext — a pure Go struct that replaces the old C-coupled parameter
passing interface in cplugin. Platform-specific loaders are now split by build tag:

//go:build linux — Unix dynamic loader via CGO (for users who opt in)
//go:build windows — Native DLL loader via syscall and golang.org/x/sys/windows,
zero CGO dependency
fallback — no-op loader for non-CGO builds, compiles clean on any target

The entrypoint (cmd/fz) no longer imports "C" at all. The binary is now fully
cross-compilable from any host to any target without a C toolchain present.

C module structs were also aligned to 64-byte cache lines to eliminate false sharing
on multi-core dispatch.

Assembler: SIMD, sync.Pool, and One Allocation Budget

The assembler hot-path in v4.1.0 was fast. In v4.2.0 it operates under a strict
zero-allocation budget on every repeated call.

Three changes made this possible:

SIMD + branchless lookups for whitespace and comment stripping.
The previous implementation used range loops with conditional branches. The rewrite
uses branchless lookup tables and SIMD-width processing to strip comments and normalize
whitespace without a single branch misprediction in the common case.

Parser recycling via sync.Pool.
Each parse call previously allocated a new parser struct. The pool holds pre-warmed
parser instances and recycles them across goroutines. Allocation churn in the assembler
is now flat under sustained parallel load.

splitArgs as a parser method with pre-allocated slice recycling.
The argument splitter was a free function that allocated a new slice on every call.
It is now a method on the pooled parser, reusing the backing array across invocations.
The slice is reset, not reallocated.

Compiler flags are parsed once via sync.Once lazy initialization. Repeated calls
to the flag parser cost a single atomic read.

FastCopy — the inner loop for instruction stream copying — was rewritten as a
branchless unrolled function using unsafe.Pointer arithmetic. No bounds checks.
No interface dispatch. Direct memory throughput.

Linker: On-Disk Symbol Cache, No nm

The linker previously invoked the nm utility to resolve symbol tables. nm is a
process fork per object file. At 1000 modules that is 1000 forks, each with exec
overhead, pipe setup, and string parsing.

v4.2.0 introduces a co-located on-disk symbol cache. Symbol data is written alongside
the object file on first build and read directly on subsequent builds. The nm binary
is never invoked in the hot path.

Object deduplication was simplified from a custom mmap-based structure to a native
Go map. The mmap routines are gone. The map is faster for the deduplication workload
and eliminates an entire category of platform-specific edge cases.

Response file generation was refactored to use bufio.Writer with f.Sync removed.
The sync was a correctness hedge that was never needed — the linker already operates
under an ordering guarantee from the task graph.

Builder and Utils: WalkDir, Zero-Copy Loops, Raw Syscalls

The builder's source discovery was rewritten around WalkDir with explicit
filepath.SkipDir support in the custom SYS_GETDENTS64 walker. Directory subtrees
that cannot contain build targets are pruned at the kernel boundary, not in userspace.

CleanDir was deduplicated — it was being called multiple times per build target in
the previous implementation. Slice allocations in the task dispatch worker were
eliminated; the dispatch loop now operates on pre-allocated task structs with
zero heap writes in the hot path.

Platform-specific file hashing:

Linux: Direct SYS_OPENAT loops with defer-based cleanup and no os.File allocation
macOS: Low-level mmap write interfaces, resource management tuned to Darwin's
unified buffer cache behavior
Windows / non-UNIX: Updated fallback stubs that compile clean and behave correctly

Unused pools were purged. Digest-to-string conversions were rewritten to use
stack-allocated byte slices instead of fmt.Sprintf.

What v4.1.0 Established

For context: v4.1.0 shipped the HADES ELF emitter with correct .symtab ordering
(local symbols before global, strict linker compliance), deterministic relocation
calculation for call and jmp offsets, and the AEGIS security layer with TOCTOU
mitigation, atomic SBOM generation, and secureVendorPath symlink validation.

The allocation regression suite and golangci-lint enforcement were introduced in
that release and remain green.

v4.2.0 builds on that foundation without breaking it.

Numbers That Matter

2.84x faster than Ninja at 1000 C modules
3.25x faster than make -j4 at 100 modules (v4.1.0, still holds)
~1.18 GB/s sustained copy throughput on i5-10310U, zero GC interference
0 allocs/op, 0 B/op in copyFileHot micro-benchmark
0 CGO dependencies in the default build path
100% golangci-lint compliance, strict config

Get It

git clone https://github.com/forgezero-cli/forgezero
cd forgezero
go build -o fz ./cmd/fz

No C toolchain required. No network calls at build time. Reproducible output on
amd64 and arm64 across Linux, Windows, and macOS.

Source, benchmarks, and the full commit log are in the repository.
If you are running large C projects and measuring build latency, the numbers are
worth verifying on your own hardware.

ForgeZero is a low-level build orchestrator written in Go. It targets deterministic,
zero-allocation execution for large-scale C and assembly projects.

Bridging the Context Gap: Providing Structural Awareness to AI Coding Agents in Go with GoGraph

Thu, 14 May 2026 15:44:55 +0000

The hardest part of using AI coding agents isn't getting them to write Go code. It's watching them burn through your context window just trying to figure out where things are.

If you’ve spent any time using Claude, Antigravity or Copilot on a medium-to-large Go codebase, you know the drill. You ask the agent to modify a core component. Before it writes a single line of code, it starts blindly running grep, guessing file paths, and sequentially cat-ing files.

By the time the agent finally maps out the upstream HTTP handlers, the database interactions, and the interface satisfactions, it has exhausted a massive chunk of its token limit. The context window is bloated with irrelevant side-material and raw text dumps. The more noisy, unstructured code you feed the agent, the higher the chance it gets confused and starts hallucinating bad logic.

Agents don't fail because they are bad at writing logic. They fail because they have to brute-force their way to structural awareness.

I got tired of watching my AI tools waste tokens and context guessing my repository structure, so I built Gograph. It’s a local static analysis engine and Model Context Protocol (MCP) server that gives your AI agents a deterministic, whole-repository structural map of your Go projects in a single, token-efficient JSON query.

Why RAG and Terminal Searching Aren’t Enough

Right now, the industry usually tries to solve the codebase context problem in two ways: vector embeddings through RAG, or by letting agents inspect the repository through terminal commands. Both approaches are useful, but neither is sufficient on its own for reliable understanding of a large Go codebase.

The issue with RAG is that vector embeddings are good at semantic retrieval. If you want to find code related to “user authentication logic,” embedding search can often surface relevant files or nearby concepts. But embeddings do not provide deterministic code intelligence. They cannot prove that UserStore.Update() satisfies the Datastore interface, identify every caller across package boundaries, or trace how an error propagates through several layers of middleware. Those relationships require parsing, type checking, and static analysis.

The issue with terminal search is that agents often fall back to tools like grep, rg, or reading files directly. These tools are valuable for exact strings, symbols, config keys, routes, and quick navigation. But plain text search cannot reliably capture relationships that only exist after the compiler understands the program. In Go, interface satisfaction is implicit, indirect calls may flow through interfaces, and behavior may depend on build tags, generated code, or package-level wiring. A search-only approach is likely to miss non-obvious dependencies.

For large Go repositories, reliable agent context needs more than semantic search and raw file inspection. It needs compiler-aware code intelligence: symbols, packages, imports, interfaces, implementations, call graphs, route mappings, test relationships, and error flows. RAG can help find relevant areas. Terminal tools can help inspect concrete files. But the agent also needs structured knowledge of how the code actually fits together.

Fixing It With Static AST Analysis

Instead of relying only on semantic similarity or raw text search, I wanted a tool that gives agents structured knowledge of a Go repository.

Gograph uses Go’s native parsing infrastructure, including go/ast and go/parser, to build a static graph of your repository. It runs entirely on your local machine: no network requests, no sending proprietary source code to third-party APIs. Its goal is to map concrete code structure such as packages, symbols, functions, methods, struct fields, imports, call sites, route wiring, tests, and recognizable dependency paths.

Gograph ships with more than 20 specialized static analysis commands, including tools to map concurrency primitives, identify oversized objects, discover potentially dead code, and extract SQL-related structure. However, I designed three primary commands specifically to act as the core structural guardrails for AI agents.

1.gograph plan

Before an agent touches a file, it can run plan. Gograph analyzes the static code graph around the symbol and returns an impact-oriented view of the surrounding code.

It can show callers, related packages, upstream HTTP routes where they are statically detectable, whether the execution path appears to touch persistence-related code, and which test files are likely to be affected.

This gives the agent a concrete starting point instead of forcing it to guess from embeddings or repeatedly read files into context.

2.gograph review

After the agent makes an edit, it can run review. This acts as a structural sanity check over the affected area.

It can flag likely breakage in routing paths, changed dependencies, stale tests, and interface-related drift where those relationships are visible to static analysis. It is not a replacement for compilation or go test. It is an earlier feedback layer that helps agents catch structural mistakes before running the full verification loop.

3.gograph errorflow

When a test fails with an error like "invalid token signature", the agent should not have to guess where that message originated. It can pass the string to errorflow.

Gograph searches for where the error is created or wrapped, then follows the static return and call path as far as it can identify it. When the path is visible in the source graph, it can show how the error moves from the originating function toward higher-level handlers or tests.

This is useful in larger Go services where errors often pass through repository, service, middleware, and handler layers before reaching the test output or API response.

What It Looks Like in Practice

Let’s say you need an AI agent to add a TenantID field to a User struct in a shared package.

If the agent relies only on raw search, it may find the struct, add the field, update the local constructor, and stop. The build may still fail because a POST /api/v1/users handler in another package initializes the struct directly, or because repository code, SQL mapping, and integration tests also need updates.

If the agent uses Gograph first, it can query the User symbol and get a structured view of the surrounding code. That view can show that the symbol is connected to a specific POST route, appears in repository code, participates in SQL-related paths, and is referenced by specific test files.

The agent now has a better bounded scope for the change. Instead of editing one obvious file and discovering failures one by one, it can update the struct, handler, persistence path, and tests in a single coherent pass.

Hooking It Up via MCP

Gograph works as a standalone CLI, but it is also designed to be consumed by AI agents through the Model Context Protocol, or MCP.

MCP is an open protocol introduced by Anthropic for connecting AI systems to local tools and data sources. Gograph ships with a built-in MCP server that operates over standard I/O.

Instead of forcing the model to read and interpret unstructured terminal output, the MCP integration gives it structured, machine-readable JSON.

For an MCP-compatible client such as Cursor or Claude Desktop, the configuration looks like this:

{
  "mcpServers": {
    "gograph": {
      "command": "gograph",
      "args": ["mcp", "/path/to/your/repository"]
    }
  }
}

Once registered, the agent can query the repository graph before editing. It can inspect the structural impact of a proposed change, identify likely affected files, and build a more grounded execution plan before writing code.

Getting Started

If you’re building in Go and tired of cleaning up after your AI tools, you can install Gograph right now:

# macOS / Linux (via Homebrew)
brew install ozgurcd/tap/gograph
# Or using Go:
go install github.com/ozgurcd/gograph/cmd/gograph@latest

Final Thoughts

AI agents work better when they are given structured context instead of raw text alone. RAG is useful for semantic retrieval. Terminal commands are useful for exact inspection. But large Go codebases also need code-aware context: packages, symbols, call paths, routes, tests, persistence boundaries, and error flows.

That is the problem Gograph is trying to solve.

If you’re building in Go and tired of cleaning up after your AI tools, give Gograph a try.

Source Code and Documentation: https://github.com/ozgurcd/gograph

If you have ideas for other static analysis heuristics that would be useful for AI context, I'd love to hear your feedback! Feel free to open an issue or start a discussion on the GitHub repository.

We Rebuilt the Kubernetes Dashboard From Scratch — Here's What We Added

Thu, 14 May 2026 01:53:51 +0000

We Rebuilt the Kubernetes Dashboard From Scratch — Here's What We Added

The official Kubernetes Dashboard was archived in January 2026. The Angular codebase was unmaintainable, the toolchain was fragile, and the upstream maintainers called it quits. We needed a dashboard for our home lab security platform — so we built one from scratch.

This is the story of what we built, why we made the decisions we did, and what makes it different from the alternatives.

Why Not Headlamp, Lens, or Rancher?

We evaluated the obvious alternatives:

Lens — desktop app, not in-cluster, commercial freemium model. Not suitable for a hardened in-cluster deployment.
Headlamp — great project, but its extensibility model relies on dynamically loaded JavaScript plugins. We preferred a dashboard with no plugin runtime and a fully auditable, static codebase.
Rancher — full multi-cluster platform, overkill for a single cluster, and it needs its own namespace footprint

We wanted something that runs in-cluster as a hardened pod, has no external dependencies beyond the Kubernetes API, and is auditable — no plugin runtime, no dynamic code loading.

One more thing the original couldn't do: work with MetalLB. It was designed around kubectl proxy and NodePort — never intended to sit behind a real in-cluster gateway. Getting it onto a MetalLB IP required Kong as the gateway, which the original had no support for.

So we forked the archived dashboard and rebuilt it.

The Stack

Frontend: React 19 + Material UI v6 + Vite + TypeScript
Backend: Four Go modules — API, Auth, Metrics Scraper, Common
Gateway: Kong 3.9 (DBless) as the in-cluster API gateway
Auth: Bearer token (Kubernetes Service Account) with CSRF protection
Deploy: Raw Kubernetes manifests — no Helm

The original Go backend contracts were preserved. Only the UI layer was replaced.

What We Shipped Beyond "Standard Dashboard"

The usual dashboard shows you workload lists, pod logs, and a shell. We added ten native features that normally require separate tools:

1. Policy Audit (Polaris-native)

14 security checks against live pod specs — no Polaris deployment needed:

Privilege escalation allowed?
Host network / host PID / host IPC?
Resource limits set?
Readiness and liveness probes defined?
Image tag is latest?
seccompProfile configured?

Each workload gets a score 0–100. The namespace gets an aggregate. Filterable by severity (Danger / Warning / Pass).

The entire thing is a single Go package reading pod specs directly from the Kubernetes API. No admission webhooks, no third-party operators.

2. Resource Efficiency (Goldilocks-style)

Compares actual CPU/memory usage (from metrics.k8s.io) against container requests and limits:

No Limits — the container has no resource limits set (dangerous)
Hot — actual usage exceeds requests (risking OOM or CPU throttling)
Cold — requests are much larger than actual usage (wasting capacity)
OK — requests and limits are reasonable

CSV export for capacity planning. With VictoriaMetrics enabled, trend arrows (↑ ↓ →) show whether usage is growing, shrinking, or stable.

3. Certificate Tracker

Parses every kubernetes.io/tls Secret across all namespaces using Go's stdlib crypto/x509. No cert-manager dependency.

Shows: Common Name, SANs, issuer, expiry date, days remaining, and a status badge (Valid / Warning ≤30d / Critical ≤7d / Expired).

4. RBAC Viewer

Joins all ClusterRoles, Roles, ClusterRoleBindings, and RoleBindings into a flat view. Filters by subject, scope, or kind. Wildcard (*) detection flags any binding that grants broad permissions.

5. AI Assistant (Claude Sonnet)

A chat drawer powered by Anthropic's Claude via SSE streaming. When opened from a pod detail page, it automatically injects the pod's spec, container statuses, and recent events as system context.

Ask it: "Why is this pod crash-looping?" and it reads the events, the image, the environment variables, and the resource limits to give you an actual answer — not a generic Kubernetes doc quote.

6. Event Timeline

Live cluster event feed refreshing every 5 seconds. Events are time-bucketed by minute, Warning events highlighted in amber, filterable by namespace and free text. Useful for watching a rolling restart or debugging a flapping pod without staring at kubectl get events -w.

7. Cluster Map

All Deployments, DaemonSets, and StatefulSets rendered as health cards grouped by namespace — zoom from 40% to 150%, filter by Error/Warning, click through to the workload detail. Useful for a quick visual sweep of the cluster when something is off.

8. Application Projects

Per-namespace project cards showing pod health (Running / Pending / CrashLoopBackOff / Failed), workload counts (Deployments, StatefulSets, DaemonSets), and CPU/memory request totals. Clicking a card navigates to the pod list filtered to that namespace. System namespaces hidden by default with a toggle.

9. Kubescape Security (auto-detected)

If Kubescape Operator is running in the cluster, a Security section appears automatically in the nav — no configuration, no feature flags. It reads Kubescape's CRDs (spdx.softwarecomposition.kubescape.io) and displays:

Security Overview — SVG donut charts for config scan pass/fail ratio and CVE severity breakdown, plus a lowest-scoring workloads table. One-page health snapshot before you drill in.
Config Scan — compliance score per workload (0–100), filterable by namespace
Vulnerabilities — CVE findings per workload with severity breakdown (Critical / High / Medium / Low)

If Kubescape is not installed, the Security section simply doesn't appear.

10. Email Notifications (Microsoft Graph API)

Two notification modes:

Health Digest — daily email with cluster health score, namespace table, top issues
Event Alerts — real-time email on CrashLoop, OOM kill, ImagePullBackOff, NodeNotReady, PVC issues. 1-hour dedup per workload so you don't get flooded.

No SMTP server needed — sends via Microsoft Graph API (works with any Microsoft 365 / Entra ID account).

Security Hardening

We ran an OWASP Top 10 audit and fixed everything we found:

No wildcard RBAC — each pod has its own ServiceAccount with least-privilege rules
NetworkPolicy default-deny — every pod has an explicit allow list; all other traffic is denied
readOnlyRootFilesystem: true on all containers except Kong (which writes Lua cache)
All capabilities dropped (drop: [ALL])
seccompProfile: RuntimeDefault on all pods
CSRF protection on all mutating POST endpoints
Bearer tokens never logged, never cached in plain text
API response cache keyed by SHA256(token) + URL — users can never see each other's cached data

RBAC-Aware UI

Every action button (Delete, Scale, Restart, Rollback, Pause) checks the user's actual Kubernetes permissions via SelfSubjectAccessReview before rendering. If the user's token doesn't have patch on daemonsets, the Rollback button is greyed out with a tooltip — not shown at all, not erroring after the click.

Rollback With Revision History

Deployments, DaemonSets, and StatefulSets all have a rollback button in the action bar. Click it and you get a revision picker:

Deployments — reads ReplicaSets annotated with deployment.kubernetes.io/revision
DaemonSets / StatefulSets — reads ControllerRevision objects (the same mechanism kubectl rollout undo uses)

Select a revision, see the container image and age, click Rollback. Same UX as kubectl rollout undo --to-revision=N but without leaving the browser.

Optional: VictoriaMetrics Backend

The dashboard ships with SQLite as the default metrics cache (same as the original). If you deploy VictoriaMetrics alongside it (one StatefulSet, one PVC — the manifest is included), the metrics scraper starts pushing to it via remote write, and you get:

Pod CPU/memory sparklines with time range toggles (1h / 6h / 24h / 7d)
Trend arrows on the Resource Efficiency page
Historical data surviving pod restarts

If you don't deploy VictoriaMetrics, nothing changes. The capabilities endpoint returns {"victoriaMetrics": false} and the UI shows nothing different.

Gateway API Support

If your cluster runs Istio, Envoy Gateway, Contour, or any other Gateway API implementation, the dashboard automatically detects gateway.networking.k8s.io in the API server's discovery endpoint and adds a Gateway API section to the nav — GatewayClasses, Gateways, HTTPRoutes. If the CRDs aren't there, the section doesn't appear.

No configuration. No feature flags.

The Architecture Decision We're Most Proud Of

Everything is native Go — no external operators, no CRD controllers, no plugin runtime.

The policy audit doesn't need Polaris deployed. The cert tracker doesn't need cert-manager. The efficiency analysis doesn't need Goldilocks or VPA. The RBAC viewer doesn't need any extra tooling.

This means:

One fewer deployment per feature
No version coupling between the dashboard and external tools
The entire security surface is one set of pods with auditable source code

For Kubescape, we read its CRDs dynamically — if Kubescape is present, the CVE and compliance data appears. If not, nothing changes. Same pattern for Gateway API.

ISMS Core Integration

The dashboard also exposes a GET /api/v1/summary endpoint — a machine-readable cluster health snapshot (node status, pod counts by phase, recent Warning events, policy audit score, cert expiry counts). An ISMS CORE connector polls this endpoint and maps the data to ISO 27001 controls, so cluster health flows into the wider security posture platform automatically.

This follows the same pattern as the Kubescape and Gateway API integrations: the dashboard is a passive provider of structured data, not a controller.

I Got Bored and Cleaned Up 150+ GitHub Repos with a Tool I Built in Go

Fri, 01 May 2026 19:11:14 +0000

We’ve all been there scrolling through GitHub and cringing at a pile of abandoned projects and forgotten forks.

I had over 150 repos and wanted to clean them up, but GitHub’s UI makes bulk deletion tedious. So I built a TUI app in Go to make it fast and simple.

It lets you search, multi-select, and delete repositories in bulk, with quick access to repo details and browser links.

In about 10 minutes, I cleared out dozens of unused repos and kept only what matters.

If your GitHub needs a cleanup: Repository

Shift-Left Code Quality: Inside DebtDrone CLI 2.0.0 and a Dual-Mode Architecture

Fri, 17 Apr 2026 19:13:20 +0000

Technical debt is a silent tax on engineering velocity. By the time it is flagged in a pull request, the cost to fix it has already multiplied.
Today, I am thrilled to announce the release of DebtDrone CLI 2.0.0—a major architectural milestone that brings enterprise-grade code analysis directly to your local terminal and CI/CD pipelines.
The engineered version 2.0.0 using a strict Ports & Adapters (Hexagonal) Architecture, transforming our statically-linked Go binary into a dual-purpose powerhouse:
️ Interactive TUI (For Developers): A lightning-fast, Bubble Tea-powered terminal interface to visually explore complexity metrics and track historical debt reduction locally.
Headless CLI (For Pipelines): A deterministic, pipeline-ready executable to enforce automated quality gates (--fail-on=high) and block bad code from ever merging.
Crucially, DebtDrone CLI 2.0.0 is powered by the exact same core analysis engine that will drive our upcoming DebtDrone SaaS platform. By upgrading today, you are getting an early, hands-on experience with the engine that is about to change how organizations map and manage code quality.

I just published a deep dive into how we built this dual-mode architecture, how we prevented TUI state bloat using a nested router pattern, and how you can start shifting your code quality checks to the left today.

Check out the full article and installation guide here: https://www.endrilickollari.com/blog/debtdrone-cli-2-release

The Go Programming Language: Everything You Need To Know

Mon, 23 Feb 2026 19:36:05 +0000

Hello, I'm Ganesh. I'm working on FreeDevTools online, currently building a single platform for all development tools, cheat codes, and TL; DRs — a free, open-source hub where developers can quickly find and use tools without the hassle of searching the internet.

In this series I will be explaining Go language. I will be covering most of the topics in Go which would be normaly used in most of the applications.

Main Goal of this series is to start from scratch and end in production grade application.

If you are already familiar with Go and just want to go in deeper like want to understand internal working of Go and how it evolved this series would be a good fit for you.

In this part, I will be explaining the history of Go and how it came out.

What is Go?

an open-source, statically typed, and compiled programming language designed at Google to make it easier to build simple, reliable, and efficient software

It combines the performance of a low-level compiled language like C++ with the readability and usability of modern dynamic languages like Python.

As you learn more about Go, you will find that it is a language that is both powerful and easy to learn.

There has been many open source projects built using Go (like listmonk, Docker, Kubernetes, etc).

Simple Hello World

Before even starting with go, let's just do a simple hello world program.

I recommend you to go with officical Go tour to learn go.

Link: Go Tour

As in every language, let's just do a simple hello world program.

package main
import "fmt"
func main() {
    fmt.Println("Hello, World!")
}

In the above code,

package main is the package name, it is the entry point of the program.

import "fmt" is the import statement, it imports the fmt package which is used to print the output.

func main() { ... } is the main function, it is the entry point of the program.

fmt.Println("Hello, World!") is the print statement, it prints the output.

In this part, we just understood the simple surface level of go and also understand the basic structure of go program.

Upcoming Part

In upcomming part I will be explaining the project structure of go project. How to setup locally and how to run it.

How My Worst Complexity Solution Beat 100% Runtime

Sun, 22 Feb 2026 22:53:29 +0000

I recently solved the Leetcode 868. Binary Gap problem in Go, and encountered something interesting.

My supposedly worst solution — with an O(n log n) time complexity — ended up beating 100% of submissions in runtime.

Meanwhile, the "optimal" space version used more memory.

That made me realise something important:

Big-O complexity might not always dominate — especially when input size is tightly bounded.

In this case, the maximum binary length was only 32 bits. Sorting a handful of integers becomes effectively constant time. The theory said one thing. The measurements told another story.

I wrote a short breakdown explaining:

Why does this happen
How online judges measure performance
When asymptotic complexity truly matters
And how to implement a truly optimal bitwise version

If you're into performance reasoning and algorithm trade-offs, you might enjoy this one.

https://dev.to/rezzcode/leetcode-sunday-4-1025

Stop Leaking API Keys in your AI Agent Logs: A Go Sidecar Approach

Thu, 05 Feb 2026 21:59:45 +0000

Stop Leaking API Keys in your AI Agent Logs: A Go Sidecar Approach

Subtitle: The Hidden Privacy Leak in your AI Agents (and why your LLM "Audit Logs" are a GDPR Nightmare)

1. The Problem

Everyone is building AI agents right now. Whether you're using LangChain, AutoGPT, or custom loops, you are almost certainly logging their work. You keep traces of every step to debug reasoning loops or monitor costs.

Here lies the pain: Everything goes into these logs. User prompts, model responses, and raw JSON payloads from APIs.

The Visualization

Imagine this scenario:

Input Log:

{"user": "aragossa", "prompt": "My key is sk-live-123456"}

What your Logging System Saved:

{"user": "aragossa", "prompt": "My key is sk-live-123456"}

If a user pastes their password, API key, or PII into the chat, or if an API returns a sensitive internal token, that data is now permanently etched into your Elasticsearch, Datadog, or S3 bucket.

The Consequence: Your fine-tuning dataset is now "poisoned" with real user data. This is a massive GDPR violation and a ticking security time bomb. You can't just "delete" it if you don't know where it is.

2. The Gap: Why usual methods fail

Regex? Good luck maintaining a regex list for every possible API key format, session token, and PII variation in existence. It’s a game of whack-a-mole you will lose.
ML-based protection? Too slow. If your agent operates in real-time, you cannot afford a 500ms roundtrip to a BERT model just to sanitize specific log lines. PII scans often become the bottleneck.
Python-native logic? Processing massive text streams in an interpreted language (like Python) adds significant CPU overhead per log line compared to a compiled Go binary. In high-throughput pipes, this latency adds up fast.
Existing Observability Tools?
Systems like Fluent Bit, Datadog, or OpenTelemetry already offer redaction and PII masking, usually via pattern rules and regex. For many workloads that’s perfectly fine. The trade‑off is that these pipelines are not optimized for AI‑agent traces: they either run late in the pipeline (after logs have already left the pod) or rely on configuration‑heavy pattern catalogs that are hard to keep up‑to‑date in a world of ever‑changing API keys and internal tokens.

Static scanners like TruffleHog shine for repositories and CI, where you scan code at rest. They’re not meant to sit inline on a hot log stream and make sub‑millisecond decisions on every line.

Where PII‑Shield is different is not in “inventing redaction”, but in the combination of techniques tailored for AI agents: entropy + bigram signals for unknown secrets, deterministic HMAC instead of *** for referential integrity, and deep JSON traversal to keep your log schemas intact while still scrubbing sensitive values.

3. The Implementation: Enter PII-Shield

Meet PII-Shield. It’s a lightweight sidecar written in Go that sits right next to your agent.

Killer Feature #1: Entropy-based Detection

We don't just search for "password=". We look for chaos.
API keys and authentication tokens naturally have high "entropy" (randomness/complexity). Normal human speech has low entropy. By calculating the mathematical complexity of strings, we can flag 64-character hex strings or base64 blobs without knowing their specific format.

Killer Feature #2: Deterministic HMAC

This is the feature that caught attention on Hacker News.
We don't just replace secrets with ***. We turn secret123 into [HIDDEN:a1b2c3].

Input Log:

{"user": "aragossa", "prompt": "My key is sk-live-123456"}

PII-Shield Output:

{"user": "aragossa", "prompt": "My key is [HIDDEN:8f2a1b]"}

Why?
This is a deterministic HMAC (Hash-based Message Authentication Code).

It allows you to trace a specific user or session across multiple log lines without knowing who they are.
It preserves Referential Integrity for debugging. You can see that "Session A" failed 5 times, but you validly cannot see the Session ID itself.

Killer Feature #3: Statistical Adaptive Threshold

PII-Shield doesn't just use a hardcoded number. It learns the "baseline noise" of your logs. By calculating the mean and standard deviation ($2\sigma$), it automatically adjusts the sensitivity to your specific environment.

4. The Logic: Sidecar Architecture

The architecture is dead simple, leveraging the power of Kubernetes sidecars or UNIX pipes.

Your agent simply writes logs to stdout. PII-Shield intercepts the stream, scans it in real-time with near-zero overhead, sanitizes it, and passes it forward.

5. The Technical Meat

Why Go? Because we need raw speed and no dependencies.

1. Entropy & Bigrams (The Math)

Here is how we calculate the "Chaos" (Entropy) of a token in scanner.go. We use a combination of Shannon Entropy, Character Class Bonuses, and English Bigram analysis.

The Bigram Check is crucial: it penalizes strings that look like valid English (common letter pairs) and boosts score for "unnatural" strings. (Note: This is optimized for English but can be disabled or tuned via PII_DISABLE_BIGRAM_CHECK for other languages).

// From scanner.go
func CalculateComplexity(token string) float64 {
    // 1. Shannon Entropy
    entropy := calculateShannon(token) 

    // 2. Class Bonus (Upper, Lower, Digit, Symbols)
    // bonus := float64(classes-1) * 0.5
    bonus := calculateClassBonus(token) 

    // 3. Bigram Check (English Likelihood)
    // Penalizes common English, boosts random noise
    bigramScore := calculateBigramAdjustment(token) 

    return entropy + bonus + bigramScore
}

2. False Positives? (Whitelists)

"Entropy is great, but won't it eat my Git Hashes or UUIDs?"
PII-Shield includes built-in Whitelists (isSafe function) for standard identifiers like UUIDs, IPv6 addresses, Git Commit hashes (SHA-1), and MongoDB ObjectIDs. This ensures your debugging data stays intact while secrets get redacted.

3. Credit Card Detection (Luhn Algorithm)

Entropy isn't enough for credit cards, as numbers often have low randomness. PII-Shield includes a high-performance implementation of the Luhn Algorithm to scan for valid card checksums in the stream (FindLuhnSequences).

4. Deep JSON Inspection

For JSON logs, PII-Shield performs deep inspection (processJSONLine), preserving the schema while redacting values.
Note: PII-Shield re-serializes JSON (using json.Marshal), which may change key order/sorting. It guarantees semantic integrity but is best used early in your pipeline, before any byte-sensitive steps (like signing or exact-diff comparisons).

5. Deterministic Redaction

Here is the HMAC logic using a secure Salt:

func redactWithHMAC(sensitiveData string) string {
    // CurrentConfig.Salt is loaded securely from env vars
    mac := hmac.New(sha256.New, currentConfig.Salt)
    mac.Write([]byte(sensitiveData))
    hash := hex.EncodeToString(mac.Sum(nil))
    // We only keep a short prefix for tracing identity
    return fmt.Sprintf("[HIDDEN:%s]", hash[:6])
}

The main loop (cmd/cleaner/main.go) is a highly efficient buffered reader:

func main() {
    reader := bufio.NewScanner(os.Stdin)
    for reader.Scan() {
        text := reader.Text()
        // Core logic: 0 allocations for safe lines
        // Imports github.com/aragossa/pii-shield/pkg/scanner
        cleaned := scanner.ScanAndRedact(text) 
        fmt.Println(cleaned)
    }
}

A Note on Scope: High-Entropy vs. Natural Language

Let's be clear: PII-Shield is laser-focused on High-Entropy secrets (API keys, tokens, auth headers) and structural patterns (Credit Cards). It is not a magic NLP bullet for detecting names like "John Smith" or free-text addresses. For that, you should treat PII-Shield as a low-latency "first line of defense" for your infrastructure, potentially complemented by heavier offline NLP tools for semantic analysis.

6. How to try it

I am looking for edge cases. If you are building AI agents, try running your trace logs through this and see what it catches (or misses).

You can run it locally with Docker:
docker run -i -e PII_SALT="mysalt" pii-shield < logs.txt

GitHub: https://github.com/aragossa/pii-shield

Why this matters:
Security often trails behind innovation. With the explosion of AI Agents, we are generating massive amounts of sensitive data in logs. PII-Shield is a "drop-in" safety net to ensure your innovation doesn't become a liability.

Technical debt isn't just messy code. It's a financial liability.

Sun, 28 Dec 2025 20:04:22 +0000

I started DebtDrone as a CLI tool to measure code complexity. It was fast and effective, but I quickly realized a critical limitation: a CLI only gives you a snapshot. It tells you your code is complex today, but it doesn't tell you if you're burning cash on maintenance or if your refactoring sprints are actually paying off.
To solve this, I’ve been architecting DebtDrone SaaS—transforming a local analyzer into a cloud platform that tracks the lifecycle of technical debt.

I just published a deep dive into the engineering journey behind this pivot, covering:

The Backend: Building a concurrent, high-performance analysis engine in Go.

The Strategy: Moving from "Linting" to "Risk Management" for CTOs.

The Future: Integrating Generative AI to not just find spaghetti code, but fix it.

If you are an engineer interested in AST-based analysis or a founder worried about system stability, this is for you.

Engineering DebtDrone: Building a High-Performance AST-Based Static Analyzer in Go

Fri, 19 Dec 2025 11:11:48 +0000

The Limitations of Lexical Analysis
In the world of static analysis, there is a distinct hierarchy of capability. At the bottom, you have lexical analysis—tools that treat code as a stream of strings. These are your grep-based linters. They are incredibly fast ($O(n)$ where $n$ is characters), but they are structurally blind.

To a regex linter, a function signature is just a pattern to match. It cannot reliably distinguish between a nested closure, a generic type definition, or a comment that looks like code.

When I set out to build DebtDrone, I wanted to measure Cognitive Complexity, not just cyclomatic complexity. Cyclomatic complexity counts paths through code (if/else/switch), but it fails to account for nesting. A flat switch statement with 50 cases is easy to read. A function with 3 levels of nested loops and conditionals is a maintenance nightmare.

To measure this accurately, lexical analysis is insufficient. We need Syntactic Analysis. We need a tool that understands the code structure exactly as the compiler does.

The Engine: Abstract Syntax Trees (AST)
DebtDrone leverages Tree-sitter, an incremental parsing system that builds a concrete syntax tree for a source file. Unlike abstract syntax trees (ASTs) generated by language-specific compilers (like Go's go/ast), Tree-sitter provides a unified interface for traversing trees across 11+ languages.

Parsing vs. Matching
Consider the following Go snippet:

func process(items []string) {
    if len(items) > 0 {              // +1 Nesting
        for _, item := range items { // +2 Nesting (1 + 1 penalty)
            if item == "stop" {      // +3 Nesting (2 + 1 penalty)
                return
            }
        }
    }
}

A regex tool might count the keywords if and for, giving this a score of 3. DebtDrone parses this into a tree structure. By traversing the tree, we can track nesting depth context. Every time we enter a Block node that is a child of an IfStatement or ForStatement, we increment a depth counter.

The score isn't just 1 + 1 + 1. It is weighted by depth:

Level 0: Base cost
Level 1: Base cost + 1 (Nesting penalty)
Level 2: Base cost + 2 (Nesting penalty)
This yields a "Cognitive Complexity" score that accurately reflects the mental overhead required to understand the function.

Architectural Decision: Why Go?
I chose Go for three primary architectural reasons:

Concurrency Primitives: Static analysis is an "embarrassingly parallel" problem. Each file can be parsed in isolation. Go's Goroutines and Channels allow DebtDrone to fan-out parsing tasks across all available CPU cores with minimal overhead.

Memory Safety & Speed: While Rust was a contender (and Tree-sitter has excellent Rust bindings), Go provided the fastest iteration loop for the CLI's UX and plumbing, while still offering near-C execution speed.

Single Binary Distribution: The ultimate goal was a zero-dependency binary that could drop into any CI/CD pipeline (GitHub Actions, GitLab CI, Jenkins) without requiring a runtime like Node.js or Python.

The Engineering Challenge: CGO and Cross-Compilation
The most significant technical hurdle was the dependency on go-tree-sitter. Because Tree-sitter is implemented in C for performance, incorporating it requires CGO (CGO_ENABLED=1).

In the Go ecosystem, CGO is often considered a "dealbreaker" for easy distribution. Standard Go cross-compilation (GOOS=linux go build) is trivial because the Go compiler knows how to generate machine code for different architectures. However, once you enable CGO, you are bound by the host system's C linker.

You cannot compile a macOS binary on a Linux CI runner using the standard gcc. You need a macOS-compatible linker and system headers.

The Solution: goreleaser-cross
To solve this, I architected the release pipeline around Dockerized Cross-Compilers. Instead of relying on the bare-metal runner, the release process spins up a container (ghcr.io/goreleaser/goreleaser-cross) that contains a massive collection of cross-compilation toolchains:

o64-clang: For building macOS (Darwin) binaries on Linux.
mingw-w64: For building Windows binaries on Linux.
aarch64-linux-gnu-gcc: For ARM64 Linux builds.
This configuration is managed via .goreleaser.yaml, where we dynamically inject the correct C compiler (CC) based on the target architecture:

builds:
  - id: debtdrone-cli
    env:
      - CGO_ENABLED=1
      # Dynamic Compiler Selection
      - CC={{ if eq .Os "darwin" }}o64-clang{{ else if eq .Os "windows" }}x86_64-w64-mingw32-gcc{{ else }}gcc{{ end }}
      - CXX={{ if eq .Os "darwin" }}o64-clang++{{ else if eq .Os "windows" }}x86_64-w64-mingw32-g++{{ else }}g++{{ end }}
    goos:
      - linux
      - darwin
      - windows
    goarch:
      - amd64
      - arm64
This setup allows a standard Ubuntu GitHub Actions runner to produce native binaries for Mac (Intel/Apple Silicon), Windows, and Linux in a single pass.

Distribution Strategy: Homebrew Taps
For v1.0.0, accessibility was key. While curl | bash scripts are common, they lack version management. I implemented a custom Homebrew Tap to treat DebtDrone as a first-class citizen on macOS.

By adding a brews section to the GoReleaser config, the pipeline automatically:

Generates a Ruby formula (debtdrone.rb) with the correct SHA256 checksums.
Commits this formula to a separate homebrew-tap repository.
Allows users to install/upgrade via brew install endrilickollari/tap/debtdrone.
Beyond the Code: Impact by Role
While the engineering behind DebtDrone is fascinating, its real value lies in how it empowers different stakeholders in the software development lifecycle.

For the Developer: The "Self-Check" Before Commit
We've all been there: you're deep in the zone, solving a complex edge case. You add a flag, then a nested if, then a loop to handle a collection. It works, but you've just created a "complexity bomb."

DebtDrone acts as a mirror. By running debtdrone check . locally, you get immediate feedback:

"Warning: processTransaction has a complexity score of 25 (Threshold: 15)."

This prompts a refactor before the code even reaches a pull request. It encourages writing smaller, more composable functions, which are inherently easier to test and debug.

For the Team Lead: Objective Code Quality
Code reviews can be subjective. "This looks too complex" is an opinion; "This function has a complexity score of 42" is a fact.

DebtDrone provides an objective baseline for discussions. It helps leads identify:

Hotspots: Which files are the most dangerous to touch?
Trends: Is the codebase getting cleaner or messier over time?
Gatekeeping: Preventing technical debt from leaking into the main branch by setting hard thresholds in CI.
For DevOps: The Quality Gate
In a CI/CD pipeline, DebtDrone serves as a lightweight, fast quality gate. Because it compiles to a single binary with zero dependencies, it can be dropped into any pipeline (GitHub Actions, GitLab CI, Jenkins) without complex setup.

It supports standard exit codes (non-zero on failure) and can output results in JSON for integration with dashboarding tools. This ensures that "maintainability" is treated with the same rigor as "passing tests."

For the Business Analyst: Velocity & ROI
Why should a business care about Abstract Syntax Trees? Because complexity kills velocity.

High cognitive complexity directly correlates with:

Longer onboarding times for new developers.
Higher bug rates due to misunderstood logic.
Slower feature delivery as developers spend more time deciphering old code than writing new code.
By investing in tools like DebtDrone, organizations are investing in their long-term agility. It's not just about "clean code"—it's about sustainable development speed.

Conclusion
DebtDrone v1.0.0 represents a shift from "linting as an afterthought" to "architectural analysis as a standard." By moving from Regex to ASTs, we eliminate false positives. By solving the CGO cross-compilation puzzle, we ensure the tool is available everywhere.

The result is a CLI that runs locally, respects data privacy, and provides immediate, actionable feedback on technical debt.

GitHub Repository: endrilickollari/debtdrone-cli

Building Herctually: An AI Research Agent written in GO

Thu, 06 Nov 2025 22:33:54 +0000

Every week, I review competitors' articles and summarize them in a report. It’s repetitive and not exactly the favorite part of my week. I have been using a few new AI tools, such as Amp, Opencode, and I thought it would be nice to have a tool that could make things easier. So I built "Herctually," an AI research assistant that automates the boring parts.

We’ll try to build Hertcually in Go, from model setup to giving it powers like web search, reading, and report writing.

But first, let's align on what an agent is. According to Thorsten Bell, an agent is “an LLM with access to tools, giving it the ability to modify something outside the context window“.

How I see it is that an agent is a large language model (LLM) that can take actions, not just talk. It can search, write, read, and execute. Think of it as a chatbot with hands.

We’ll need:

Go
Access to a model (via OpenRouter, so we can easily test GPT-4, Claude, etc.)
A use case — in our case, automating research.
A few tools — to extend the model’s abilities.

Setting Up the Project

mkdir herctually
cd herctually
go mod init herctually
touch main.go
mkdir agent
touch agent/agent.go

Now, in our main.go file, we would like to set up the structure for running our agent. Some errors may appear initially, they’ll resolve once we add the missing pieces.

// main.go


package main

import (
 "bufio"
 "context"
 "fmt"
 "log"
 "os"

 "github.com/openai/openai-go/v3"
 "github.com/openai/openai-go/v3/option"
 "herctually/agent"
)

func main() {

 apiKey := os.Getenv("OPENROUTER_APIKEY")
 if apiKey == "" {
  log.Panic("OPENROUTER_APIKEY environment variable is required")
  os.Exit(1)
 }

 baseURL := os.Getenv("OPENROUTER_BASEURL")
 if baseURL == "" {
  log.Panic("OPENROUTER_BASEURL environment variable is required")
  os.Exit(1)
 }

 scanner := bufio.NewScanner(os.Stdin)
 getUserMessage := func() (string, bool) {
  if !scanner.Scan() {
   return "", false
  }

  return scanner.Text(), true
 }

 llm := openai.NewClient(
  option.WithAPIKey(apiKey),
  option.WithBaseURL(baseURL),
 )

 ag := agent.New(&llm, getUserMessage)

 if err := ag.Run(context.Background()); err != nil {
  fmt.Printf("Error: %s\n", err)
 }
}

Now, let's add the agent code.

// agent/agent.go

package agent

import (
 "context"
 "fmt"

 "github.com/openai/openai-go/v3"
)

type Agent struct {
 llm            *openai.Client
 getUserMessage func() (string, bool)
}

func New(llm *openai.Client, getUserMessage func() (string, bool)) *Agent {
 return &Agent{
  llm:            llm,
  getUserMessage: getUserMessage,
 }
}

var systemPrompt = `<role>
   You are 'Herctually,' a sharp, logical, and strategic research assistant, focused on clarity and precise argumentation.
   </role>
   <personality>
   Polite, confident, analytical. You challenge ideas before you support them. You enjoy exposing weak logic. You’re not here to please, you’re here to clarify.
   </personality>
   <rules>
   - Be concise but deep.
   - Separate facts, inferences, and speculation.
   - Always surface what others overlook.
   - Correct errors ruthlessly, including the user’s.
   </rules>
   <goal>
   Deliver insights with precision, not politeness. Your output should feel like a distilled intelligence briefing from someone who actually thinks.
   </goal>`

func (a *Agent) Run(ctx context.Context) error {
 conversation := []openai.ChatCompletionMessageParamUnion{
  openai.SystemMessage(systemPrompt),
 }

 fmt.Println("Chat with Herctually (use 'ctrl-c' to quit)")

 for {
  fmt.Print("\u001b[94mYou\u001b[0m: ")
  userInput, ok := a.getUserMessage()
  if !ok {
   break
  }
  userMessage := openai.UserMessage(userInput)
  conversation = append(conversation, userMessage)

  message, err := a.runInference(ctx, conversation)
  if err != nil {
   return err
  }
  conversation = append(conversation, message.Choices[0].Message.ToParam())
  for _, content := range message.Choices {
   fmt.Printf("\u001b[93mHerctually\u001b[0m: %s\n", content.Message.Content)
  }
 }

 return nil
}

func (a *Agent) runInference(ctx context.Context, conversation []openai.ChatCompletionMessageParamUnion) (*openai.ChatCompletion, error) {

 message, err := a.llm.Chat.Completions.New(ctx, openai.ChatCompletionNewParams{
  Model:               openai.ChatModelGPT4o,
  MaxCompletionTokens: openai.Int(1024),
  Messages:            conversation,
 })
 return message, err
}

Lastly, let's add our environment variables, install our dependencies, and run it.

export OPENROUTER_APIKEY="sk-xxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export OPENROUTER_BASEURL="https://openrouter.ai/api/v1"

# Download the dependencies
go mod tidy
# Run it
go run main.go

Then we can just talk to Herctually, like this:

$ go run main.go
Chat with Herctually (use 'ctrl-c' to quit)
You: Hi
Herctually: Greetings. Do you have a specific question or topic you'd like to discuss? I'm here to provide clear and precise insights.
You: What is https://oreoluwabs.com/ about
Herctually: I currently do not have the capability to browse the internet in real-time or access external content. However, I can offer guidance on how to assess a website's legitimacy or purpose.
You:

Now we have a basic agent that has a personality, we can ask and can respond on a subject matter!

But how do we make her do the things we mentioned, search the web, read, and write reports? The answer is Tools. Models allow us to enhance their output by calling tools.

Let’s give her the ability to be able to search the web.

Let's make an agent/tools.go file.

// agent/tools.go
package agent

import (
 "encoding/json"
 "fmt"
 "io"
 "io/fs"
 "net/http"
 "os"
 "path"
 "path/filepath"
 "strings"

 "github.com/openai/openai-go/v3"
)

type ToolDefinition struct {
 Name        string                    `json:"name"`
 Description string                    `json:"description"`
 InputSchema openai.FunctionParameters `json:"input_schema"`
 Function    func(input json.RawMessage) (string, error)
}

A tool requires a Name we can use as an identifier, a description to describe what the tool can do, a schema (usually jsonschema) to describe what parameters the tool has and requires, and lastly, the function to run.

We would need to make this update in agent/agent.go. This allows us to specify what tools our agent has access to.

// agent/agent.go

type Agent struct {
 llm            *openai.Client
 getUserMessage func() (string, bool)
 tools          []ToolDefinition
}

func New(llm *openai.Client, getUserMessage func() (string, bool), tools []ToolDefinition) *Agent {
 return &Agent{
  llm:            llm,
  getUserMessage: getUserMessage,
  tools:          tools,
 }
}

func (a *Agent) Run(ctx context.Context) error {
 conversation := []openai.ChatCompletionMessageParamUnion{
  openai.SystemMessage(systemPrompt),
 }

 fmt.Println("Chat with Herctually (use 'ctrl-c' to quit)")

 readUserInput := true
 for {
  if readUserInput {
   fmt.Print("\u001b[94mYou\u001b[0m: ")
   userInput, ok := a.getUserMessage()
   if !ok {
    break
   }
   userMessage := openai.UserMessage(userInput)
   conversation = append(conversation, userMessage)
  }

  message, err := a.runInference(ctx, conversation)
  if err != nil {
   return err
  }
  conversation = append(conversation, message.Choices[0].Message.ToParam())

  toolResults := []openai.ChatCompletionMessageParamUnion{}

  toolCalls := message.Choices[0].Message.ToolCalls
  for _, call := range toolCalls {
   result := a.executeTool(call.ID, call.Function.Name, []byte(call.Function.Arguments))

   toolResults = append(toolResults, result)
  }

  for _, content := range message.Choices {
   if content.Message.Content != "" {
    fmt.Printf("\u001b[93mHerctually\u001b[0m: %s\n", content.Message.Content)
   }
  }

  if len(toolResults) == 0 {
   readUserInput = true
   continue
  }
  readUserInput = false

  for _, ccmtcu := range toolResults {
   conversation = append(conversation, ccmtcu)
  }
 }
 return nil
}

func (a *Agent) executeTool(id, name string, input json.RawMessage) openai.ChatCompletionMessageParamUnion {
 var toolDef ToolDefinition
 var found bool

 for _, tool := range a.tools {
  if tool.Name == name {
   toolDef = tool
   found = true
   break
  }
 }

 if !found {
  return openai.ToolMessage("tool not found", id)
 }

 fmt.Printf("\u001b[92mtool\u001b[0m: %s(%s)\n", name, input)
 response, err := toolDef.Function(input)
 if err != nil {
  return openai.ToolMessage(err.Error(), id)
 }

 return openai.ToolMessage(response, id)
}


func (a *Agent) runInference(ctx context.Context, conversation []openai.ChatCompletionMessageParamUnion) (*openai.ChatCompletion, error) {
 opentools := []openai.ChatCompletionToolUnionParam{}

 for _, tool := range a.tools {
  opentools = append(opentools, openai.ChatCompletionToolUnionParam{
   OfFunction: &openai.ChatCompletionFunctionToolParam{
    Function: openai.FunctionDefinitionParam{
     Name:        tool.Name,
     Description: openai.String(tool.Description),
     Parameters:  tool.InputSchema,
    },
   },
  })
 }

 message, err := a.llm.Chat.Completions.New(ctx, openai.ChatCompletionNewParams{
  Model:               openai.ChatModelGPT4o,
  MaxCompletionTokens: openai.Int(1024),
  Messages:            conversation,
  Tools:               opentools,
 })
 return message, err
}

Now we can create our first tool definition, web_search.

// agent/tools.go


import (
 "encoding/json"
 "fmt"
 "io"
 "io/fs"
 "net/http"
 "os"
 "path"
 "path/filepath"
 "strings"

 // Add this
 "github.com/invopop/jsonschema"
 "github.com/openai/openai-go/v3"
)


type SurfTheWebInput struct {
 Url string `json:"url" jsonschema_description:"The url to fetch data from."`
}

var SurfTheWebDefinition = ToolDefinition{
 Name:        "web_search",
 Description: "Search the web for information.",
 InputSchema: SurfTheWebInputSchema,
 Function:    SurfTheWeb,
}
var SurfTheWebInputSchema = GenerateSchema[SurfTheWebInput]()

func SurfTheWeb(input json.RawMessage) (string, error) {
 surfWebInput := SurfTheWebInput{}
 err := json.Unmarshal(input, &surfWebInput)
 if err != nil {
  panic(err)
 }

 req, err := http.NewRequest("GET", surfWebInput.Url, nil)
 if err != nil {
  return "", err
 }

 client := &http.Client{}
 resp, err := client.Do(req)
 if err != nil {
  return "", err
 }
 defer resp.Body.Close()

 if resp.StatusCode != http.StatusOK {
  return "", fmt.Errorf("search api returned non-200 status: %s", resp.Status)
 }

 bodyBytes, err := io.ReadAll(resp.Body)
 if err != nil {
  return "", fmt.Errorf("failed to read response body: %w", err)
 }
 bodyString := string(bodyBytes)

 return bodyString, nil
}


func GenerateSchema[T any]() openai.FunctionParameters {
 reflector := jsonschema.Reflector{
  AllowAdditionalProperties: false,
  DoNotReference:            true,
 }

 var v T
 schema := reflector.Reflect(v)

 return openai.FunctionParameters{
  "type":       schema.Type,
  "properties": schema.Properties,
  "required":   schema.Required,
 }
}

// main.go

func main() {
    // [... previous code ...]
 ag := agent.New(&llm, getUserMessage,
  []agent.ToolDefinition{
   agent.SurfTheWebDefinition,
  })
 // [... previous code ...]
}

go mod tidy

Now let's run our project.

$ go run main.go
Chat with Herctually (use 'ctrl-c' to quit)
You: Hi
Herctually: Hello. What\'s on your mind?
You: What is https://oreoluwabs.com/ about
tool: web_search({"url":"https://oreoluwabs.com/"})
Herctually: The website "Oreoluwa Salami" presents a software developer based in Lagos, Nigeria. With over five years of experience, Oreoluwa is skilled in HTML, CSS, JavaScript, and various frameworks. The focus is on creating responsive and user-friendly web applications, with an emphasis on engaging user experiences. The site highlights their expertise in scalable and accessible web and mobile application development. It includes sections for projects, articles, and contact information, aiming to showcase professional capabilities and invite collaborations. If you need further specific details, check the website directly.
You:

Now that she can search the web, let's allow her to be able to write and read reports

// agent/tools.go

type EditFileInput struct {
 Path   string `json:"path" jsonschema_description:"The path to the file"`
 OldStr string `json:"old_str" jsonschema_description:"Text to search for - must match exactly and must only have one match exactly"`
 NewStr string `json:"new_str" jsonschema_description:"Text to replace old_str with"`
}

var EditFileDefinition = ToolDefinition{
 Name: "edit_file",
 Description: `Make edits to a text file.
 Replaces 'old_str' with 'new_str' in the given file. 'old_str' and 'new_str' MUST be different from each other.
 If the files specified with the path don't exist, they will be created.`
 InputSchema: EditFileInputSchema,
 Function:    EditFile,
}
var EditFileInputSchema = GenerateSchema[EditFileInput]()

func EditFile(input json.RawMessage) (string, error) {
 editFileInput := EditFileInput{}
 err := json.Unmarshal(input, &editFileInput)
 if err != nil {
  return "", err
 }

 if editFileInput.Path == "" || editFileInput.OldStr == editFileInput.NewStr {
  return "", fmt.Errorf("invalid input parameters")
 }

 content, err := os.ReadFile(editFileInput.Path)
 if err != nil {
  if os.IsNotExist(err) && editFileInput.OldStr == "" {
   return createNewFile(editFileInput.Path, editFileInput.NewStr)
  }
 }

 oldContent := string(content)
 newContent := strings.Replace(oldContent, editFileInput.OldStr, editFileInput.NewStr, -1)

 if oldContent == newContent && editFileInput.OldStr != "" {
  return "", fmt.Errorf("old_str not found in file")
 }

 err = os.WriteFile(editFileInput.Path, []byte(newContent), 0644)
 if err != nil {
  return "", nil
 }

 return "Ok", nil
}

func createNewFile(filePath, content string) (string, error) {
 dir := path.Dir(filePath)
 if dir != "." {
  err := os.Mkdir(dir, 0755)
  if err != nil {
   return "", fmt.Errorf("failed to create a directory: %w", err)
  }
 }

 err := os.WriteFile(filePath, []byte(content), 0644)
 if err != nil {
  return "", fmt.Errorf("failed to create file: %w", err)
 }

 return fmt.Sprintf("Successfully created file %s", filePath), nil
}



type ListFilesInput struct {
 Path string `json:"path" jsonschema_description:"Optional relative path to list files from. Defaults to current directory if not provided."`
}

var ListFilesDefinition = ToolDefinition{
 Name:        "list_files",
 Description: "List files and directories at a given path, if no path is provided, list files in the current directory.",
 InputSchema: ListFilesInputSchema,
 Function:    ListFiles,
}
var ListFilesInputSchema = GenerateSchema[ListFilesInput]()

func ListFiles(input json.RawMessage) (string, error) {
 listFilesInput := ListFilesInput{}
 fmt.Println(string(input))
 err := json.Unmarshal(input, &listFilesInput)
 if err != nil {
  panic(err)
 }
 dir := "."
 if listFilesInput.Path != "" {
  dir = listFilesInput.Path
 }

 var files []string
 err = filepath.Walk(dir, func(path string, info fs.FileInfo, err error) error {
  if err != nil {
   return err
  }

  relPath, err := filepath.Rel(dir, path)
  if err != nil {
   return err
  }

  if relPath != "." {
   if info.IsDir() {
    files = append(files, relPath+"/")
   } else {
    files = append(files, relPath)
   }
  }
  return nil
 })

 result, err := json.Marshal(files)
 if err != nil {
  return "", err
 }

 return string(result), nil
}


var ReadFileDefinition = ToolDefinition{
 Name:        "read_file",
 Description: "Read the contents of a given relative file path.",
 InputSchema: ReadFileInputSchema,
 Function:    ReadFile,
}

type ReadFileInput struct {
 Path string `json:"path" jsonschema_description:"The relative path of a file in the working directory."`
}

var ReadFileInputSchema = GenerateSchema[ReadFileInput]()

func ReadFile(input json.RawMessage) (string, error) {
 readFileInput := ReadFileInput{}
 err := json.Unmarshal(input, &readFileInput)
 if err != nil {
  panic(err)
 }

 content, err := os.ReadFile(readFileInput.Path)
 if err != nil {
  return "", err
 }

 return string(content), nil
}

$ go run main.go
Chat with Herctually (use 'ctrl-c' to quit)
You: Hi name is Ore! How is it going?
Herctually: Hello, Ore! My name is Herctually. I'm here to help you reason through things logically. How can I assist you today?
You: Analyse and write a report on https://twothreads.app/. Write the report in two threads.md file!
tool: web_search({"url":"https://twothreads.app/"})
tool: edit_file({"path":"twothreads.md","old_str":"","new_str":"# Two Threads - AI-Powered Wardrobe Management & Outfit Recommendations\n\n## Overview\n\n**Website:** [Two Threads](https://twothreads.app/)\n\nTwo Threads is an AI-powered application aimed at revolutionizing wardrobe management and outfit recommendations. It addresses the common frustration of \"having nothing to wear\" by providing AI-driven solutions tailored to individual styles, weather conditions, and occasions.\n\n### Key Features\n- **Wardrobe Management:** Allows users to catalog and organize their clothing with photos, tags, and details.\n- **AI Outfit Recommendations:** Provides personalized suggestions that consider the weather, occasion, and user style preferences.\n- **Style Tracking:** Monitors fashion evolution and gives insights to refine tastes.\n- **AI Styling Assistant \"Andi\":** Offers real-time fashion advice and inspiration.\n\n## User Experience\n\nThe platform aims to streamline the decision-making process linked to daily dressing routines. Whether it's cataloging current wardrobe items or getting fresh outfit ideas, the service promises to transform how users engage with their clothing.\n\n### How It Works\n1. **Add Your Wardrobe:** Upload photos and details of clothing items to build a personalized closet.\n2. **Get Recommendations:** Receive tailored outfit suggestions based on input details like mood or occasion.\n3. **Track & Refine:** Log wardrobe usage and give feedback for refined future suggestions.\n4. **Style Evolution:** Review fashion habits and adapt wardrobe choices over time.\n\n## Pricing\n\n- **Free:** Allows up to 50 clothing items and provides basic AI recommendations, community support.\n- **Pro:** Priced at $3/month, offering unlimited clothing entries, unlimited outfit suggestions, AI-powered styling assistance, and priority support.\n\n## Conclusion\nTwo Threads is targeting individuals looking to make their wardrobe choices more efficient and stylish. It combines practical workability with a personal styling assistant for users seeking to overcome fashion fatigue."})
Herctually: The report on Two Threads has been written and saved to a file named `twothreads.md`. If you need any more details or further analysis, feel free to ask!
You:

Conclusion

Now we have Herctually not just a chatbot, but an assistant that can think, search, read, and write. The goal wasn’t to build something huge, but to make the boring weekly research process faster. Now it can search, read, and write reports on its own and as an addon to understand how agents actually work: a loop between a model, tools, and your input.

From here, you can add memory, better web reading, reporting templates or whatever you want.

Building a Kubernetes Operator in Go with Kube-Shift

Sun, 20 Jul 2025 07:50:26 +0000

Kubernetes has become the de-facto standard for container orchestration. As its adoption grows, so does the need for extending its capabilities to manage complex, stateful applications. This is where Kubernetes Operators come in. In this article, we'll explore how to build a custom Kubernetes Operator from scratch using Go and the controller-runtime library. We'll use kube-shift, a custom operator for database schema migrations, as a real-world example to guide us through the process.

The "Why": What Problem Do Operators Solve?

Before we dive into the code, let's understand the problem operators solve. Managing applications on Kubernetes often involves more than just deploying a set of pods. Many applications require complex lifecycle management, including installation, upgrades, and handling failures. Operators automate these tasks by extending the Kubernetes API with Custom Resource Definitions (CRDs) and a custom controller to manage them.

The kube-shift project is a perfect example. It introduces a DatabaseMigration resource to Kubernetes, allowing you to manage database schema changes as part of your deployment process, just like any other Kubernetes resource.

Setting the Stage: Project Scaffolding with Kubebuilder

The kube-shift operator, like many Go-based operators, is built using the Kubebuilder framework. Kubebuilder provides a set of tools to quickly scaffold a new operator project, including the boilerplate for CRDs, controllers, and other necessary components.

The entry point of our operator is cmd/main.go This file is responsible for setting up and running the controller manager.

// cmd/main.go
package main
 
import (
// ... imports
"github.com/mohit-nagaraj/kube-shift/api/v1alpha1"
"github.com/mohit-nagaraj/kube-shift/internal/controller"
// ...
)
 
func main() {
// ... flag parsing and setup

mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
// ... options
})
if err != nil {
setupLog.Error(err, "unable to start manager")
os.Exit(1)
}
 
if err = (&controller.DatabaseMigrationReconciler{
Client: mgr.GetClient(),
Scheme: mgr.GetScheme(),
}).SetupWithManager(mgr); err != nil {
setupLog.Error(err, "unable to create controller", "controller", "DatabaseMigration")
os.Exit(1)
}
 
// ...
}

Here, we create a new manager and register our DatabaseMigrationReconciler with it. The manager is responsible for running the controller and managing its lifecycle.

Defining Our Custom Resource: The DatabaseMigration CRD

The first step in creating our operator is to define the custom resource it will manage. This is done in api/v1alpha1/databasemigration_types.go. This file defines the Go types that represent our DatabaseMigration CRD.

// api/v1alpha1/databasemigration_types.go
package v1alpha1
 
import (
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)
 
// DatabaseMigrationSpec defines the desired state of DatabaseMigration
type DatabaseMigrationSpec struct {
Database  DatabaseConfig  `json:"database"`
Migration MigrationConfig `json:"migration"`
}
 
// DatabaseMigrationStatus defines the observed state of DatabaseMigration
type DatabaseMigrationStatus struct {
Phase   MigrationPhase `json:"phase,omitempty"`
Message string         `json:"message,omitempty"`
}
 
// +kubebuilder:object:root=true
// +kubebuilder:subresource:status
 
// DatabaseMigration is the Schema for the databasemigrations API
type DatabaseMigration struct {
metav1.TypeMeta   `json:",inline"`
metav1.ObjectMeta `json:"metadata,omitempty"`
 
Spec   DatabaseMigrationSpec   `json:"spec,omitempty"`
Status DatabaseMigrationStatus `json:"status,omitempty"`
}

The DatabaseMigration struct embeds metav1.TypeMeta and metav1.ObjectMeta, which are common to all Kubernetes objects. The Spec field defines the desired state of our resource, while the Status field represents its current state.

The Heart of the Operator: The Controller and Reconciliation Loop

With our CRD defined, we need a controller to act on it. The controller's logic is implemented in internal/controller/databasemigration_controller.go. The core of the controller is the Reconcile function. This function is called every time a DatabaseMigration resource is created, updated, or deleted.

// internal/controller/databasemigration_controller.go
 
// DatabaseMigrationReconciler reconciles a DatabaseMigration object
type DatabaseMigrationReconciler struct {
client.Client
Scheme *runtime.Scheme
Log    logr.Logger
// ... other fields
}
 
// +kubebuilder:rbac:groups=database.mohitnagaraj.in,resources=databasemigrations,verbs=get;list;watch;create;update;patch;delete
// ... other rbac markers
 
func (r *DatabaseMigrationReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
log := r.Log.WithValues("databasemigration", req.NamespacedName)
 
// your logic here
 
return ctrl.Result{}, nil
}

The Reconcile function receives the name and namespace of the DatabaseMigration resource that triggered the event. It's the reconciler's job to fetch the resource and take the necessary actions to bring the system to the desired state defined in the resource's Spec. This could involve creating jobs, pods, or other resources to perform the database migration.

Advanced Reconciliation: Beyond the Basics

A robust operator does more than just create resources. kube-shift demonstrates several advanced concepts:

Status Updates: The controller updates the Status field of the DatabaseMigration resource to reflect the current state of the migration. This provides valuable feedback to users.
Finalizers: To ensure graceful cleanup, kube-shift uses a finalizer. The DatabaseMigrationFinalizer is added to the resource on creation. This prevents the resource from being deleted until the controller has performed any necessary cleanup tasks.
Leader Election: In a high-availability setup, you might run multiple instances of your operator. Leader election ensures that only one instance is active at a time, preventing conflicts. This is configured in cmd/main.go.

Testing Your Operator

Testing is crucial for any production-grade software. kube-shift includes both unit and integration tests.

Unit Tests: These tests focus on individual components of the operator in isolation.
Integration Tests: The project uses the envtest package to run integration tests against a real Kubernetes API server. You can see this in internal/controller/suite_test.go, which sets up a test environment for the controller tests.

Conclusion

Building a Kubernetes Operator is a powerful way to extend Kubernetes and automate complex application management tasks. By leveraging tools like Kubebuilder and controller-runtime, you can create robust, production-ready operators. The kube-shift project is an excellent example of how to apply these concepts to solve a real-world problem.

To learn more, I encourage you to explore the kube-shift repository on GitHub. You'll find the complete source code, along with more details on how to build, deploy, and use the operator. Happy coding!

Gopher It! Your Go-To Guide for Glorious Go Backends

Sun, 20 Jul 2025 05:59:41 +0000

Hey there, fellow code wranglers and digital alchemists! Ever felt like your backend code is a tangled mess of spaghetti, duct tape, and existential dread? Yeah, we’ve all been there. But what if I told you there's a shimmering, concurrent, and surprisingly fun path to backend nirvana? Enter Golang, or simply "Go," the language that’s making developers say, "Gopher it!" (Pun absolutely intended).
Now, before you scoff and retreat to your comfort zone of Node.js callbacks or Java's verbose rituals, give Go a chance. It's like that super-efficient friend who also happens to tell surprisingly good jokes. Let's dive deep, but keep it breezy, into why Go is becoming a heavyweight champion in the backend arena.

The Go Philosophy: Simple, Fast, and No Shenanigans

Imagine a language designed by folks who truly understand the pain points of large-scale systems. They said, "Let's ditch the inheritance hierarchies that make your head spin, let's make concurrency easy, and let's compile to a single, tiny binary that can run almost anywhere." And thus, Go was born.
It's not object-oriented in the classical sense, which can throw off some OOP purists. But honestly, sometimes less is more. Go favors composition over inheritance, which often leads to more flexible and understandable code. Think of it as building with LEGOs instead of trying to sculpt a masterpiece from a single, giant block. You get the picture.
Goroutines and Channels: Your Concurrency Superpowers (No Capes Required)
This is where Go truly shines brighter than a thousand suns (or at least, a thousand poorly optimized threads). Concurrency in Go is handled by goroutines and channels. Forget callback hell, mutexes that make you want to pull your hair out, or the sheer terror of deadlocks.

Goroutines: These are lightweight, independently executing functions. Think of them as incredibly efficient, miniature threads managed by the Go runtime, not the operating system. You can spin up thousands, even millions, of them without breaking a sweat. It's like having an army of tiny, dedicated workers, each doing their part, and they're all super polite and don't trip over each other.
package main

import (
"fmt"
"time"
)

func fetchData(url string, ch chan string) {
// Simulating some network latency
time.Sleep(2 * time.Second)
ch <- fmt.Sprintf("Data from %s: All good in the hood!", url)
}

func main() {
urls := []string{"api.example.com/users", "api.example.com/products", "api.example.com/orders"}
results := make(chan string)

for _, url := range urls {
go fetchData(url, results) // Launch a goroutine for each URL
}

for i := 0; i < len(urls); i++ {
fmt.Println(<-results) // Receive results from the channel
}

fmt.Println("All data fetched! Time for a coffee break.")
}

In this snippet, we're fetching data from multiple URLs concurrently. Each fetchData call runs in its own goroutine, and results are sent back via a channel. No waiting around! It’s so efficient, it almost feels like cheating.
Channels: These are the pipes through which goroutines communicate. They allow goroutines to send and receive values safely, preventing race conditions and making concurrent programming a breeze. Imagine them as a well-organized pneumatic tube system for your data. No more yelling across the room to share information!

This "Communicating Sequential Processes" (CSP) model, inspired by Tony Hoare, is incredibly powerful. It simplifies the mental model of concurrency from "sharing memory by communicating" to "communicating by sharing memory." Wait, that's not right. It's "Don't communicate by sharing memory; instead, share memory by communicating." Yeah, that's the one! It radically reduces the complexity of building highly concurrent systems.
Batteries Included: The Standard Library (It's Glorious!)

One of Go's unsung heroes is its incredibly rich and well-documented standard library. Need to build a web server? net/http has you covered. Working with JSON? encoding/json is your friend. Cryptography? crypto. File I/O? os. It’s like Go hands you a fully loaded toolkit the moment you start. You rarely find yourself hunting for third-party libraries for fundamental tasks.

This means less dependency hell, fewer "left-pad" moments (if you know, you know), and more time actually building your application instead of managing an ecosystem of packages. It’s practical, pragmatic, and designed for getting things done.
Error Handling: Explicit, Not Exceptions
Go's error handling might seem a bit... verbose at first glance. Instead of exceptions that jump around like a startled cat in a room full of rocking chairs, Go uses multiple return values, with the last one typically being an error interface.

func getUser(id int) (User, error) {
if id < 1 {
return User{}, fmt.Errorf("invalid user ID: %d", id)
}
// ... database lookup logic ...
return User{ID: id, Name: "Gopher McGoFace"}, nil
}

func main() {
user, err := getUser(0)
if err != nil {
fmt.Printf("Error fetching user: %v\n", err)
return
}
fmt.Printf("User found: %+v\n", user)
}

While some might grumble about the if err != nil boilerplate, it forces you to explicitly handle errors. This leads to more robust and predictable code. No more "silent" errors that only surface at 3 AM when production is burning. It’s like Go nudges you and says, "Hey, buddy, you might want to check if that went okay." And honestly, that little nudge saves a lot of headaches.

Tooling: Go's Secret Weapon (Okay, Not So Secret)

Go comes with an amazing set of built-in tools that make development a joy:

go fmt: Automatically formats your code. No more debates about tabs vs. spaces! Your codebase will look consistent across all developers. It's like a universal peace treaty for code style.

go run: Compiles and runs your Go program in one go (pun again!).

go build: Compiles your code into a single, statically linked binary. Deploying a Go app often means just copying one file. Yes, one file. No elaborate runtime dependencies, no Docker images the size of a small moon (unless you want them). It's incredibly refreshing.

go test: Built-in testing framework. Writing tests in Go is straightforward and encouraged.

go mod: Superb module management for dependencies. It’s intuitive and works like a charm.

This comprehensive tooling ecosystem means you spend less time configuring your environment and more time actually coding. It's truly a developer's dream.

Why Go for Your Next Backend Project?

Performance: Go is compiled to machine code, making it blazing fast. For high-throughput services, it's a serious contender.
Concurrency: As we gushed about, goroutines and channels make concurrent programming approachable and powerful. Building scalable services becomes a joy, not a chore.
Simplicity & Readability: The language itself is small and easy to learn. Its explicit nature makes Go code incredibly readable, even for complex systems.
Deployment: Single binaries are a deployment dream. CI/CD pipelines become simpler and faster.
Community & Ecosystem: Go has a vibrant and growing community, with excellent libraries and frameworks for web development (like Gin, Echo), database access, and more.
A Few "Gotchas" (Because Nothing's Perfect)
No Generics (until Go 1.18): This was a common complaint, leading to some boilerplate for generic data structures. However, with Go 1.18 and later, generics are finally here, making the language even more versatile! Hallelujah!
Error Handling Verbosity: As mentioned, if err != nil can get repetitive, but it’s a design choice for explicit error management. Embrace the checks, they're your friends.
Strictness: Go is opinionated. If you declare a variable and don't use it, the compiler will yell at you. This keeps your code clean but can be annoying for quick experiments. Consider it tough love from the compiler.

Conclusion: Give Go a Whirl!

If you're looking for a language that combines performance, ease of concurrency, and straightforward development, Go is absolutely worth your time. It encourages good practices, keeps things simple, and lets you build robust, scalable backends without the usual headaches.

So, next time you're about to embark on a new backend adventure, don't just stand there. Gopher it! Your future self, and your server logs, will thank you.

Happy coding, and may your goroutines always be efficient!

Controlling Memory and CPU Utilization for Go Apps in Kubernetes: GOMEMLIMIT and GOMAXPROCS

Mon, 07 Jul 2025 00:19:13 +0000

Controlling Memory and CPU Utilization for Go Apps in Kubernetes: `GOMEMLIMIT` and `GOMAXPROCS`

While running Go apps in Kubernetes, we have to control both CPU and memory to avoid instability, performance issues, or unintentional pod restarts. Go gives us two potent environment variables to achieve this: GOMEMLIMIT and GOMAXPROCS. This article details how to use them in Kubernetes correctly, what to look out for, and production deployment best practices.

`GOMEMLIMIT`: Memory Usage Control

What is it?

GOMEMLIMIT is an environment variable introduced in Go 1.19. This specifies the maximum memory limit that the Go GC will try to remain below.

Setting it up in Kubernetes

It can also be defined directly as an environment variable:

env:
- name: GOMEMLIMIT
  value: "512MiB"

Or you can automatically bind it to the container memory limit with the Downward API:

env:
- name: GOMEMLIMIT
  valueFrom:
    resourceFieldRef:
      resource: limits.memory

You must have resources.limits.memory specified in order for this to function. Otherwise, the variable will be empty.

Full example:

apiVersion: v1
kind: Pod
metadata:
  name: go-app
spec:
  containers:
  - name: go-container
    image: your-go-image
    resources:
      limits:
        memory: "512Mi"
    env:
    - name: GOMEMLIMIT
      valueFrom:
        resourceFieldRef:
          resource: limits.memory

Caveats and Risks

Often GC cycles: If the threshold is too narrow then GC will occur frequently and lead to higher CPU activity.
Slower performance: Application performance slows down because GC is executed frequently.
OOMKill still an option: In the event memory spikes quicker than GC can catch up, the container can nonetheless be terminated.
Unbounded non-heap memory: Non-heap memory is not monitored: memory from cgo allocations, mmap allocations, or big slices is unmonitored

Recommendations

Set GOMEMLIMIT to a little below your container’s memory limit (e.g., 450MiB if the limit is 512MiB).
Test under load to monitor GC behavior.
Make use of Go metrics (runtime/metrics) and pprof to examine memory use.

`GOMAXPROCS`: CPU Concurrency Control

What is it?

GOMAXPROCS determines the max number of OS threads to execute Go code concurrently. Go defaults to the number of visible CPU cores — but this can be misleading in containers.

Issues in Kubernetes

Even if your container enforces a CPU limit (e.g., 1 CPU), Go can uncover more cores (e.g., the entire host’s number of CPUs) and cause GOMAXPROCS to become too large, leading to:

Overcommitted CPU usage
Unfair scheduling
Throttling by kubelet or kernel

Putting it in place

Do not hardcode GOMAXPROCS from container limits directly,

resources:
  limits:
    cpu: "0.5"

This will not directly convert to an integer and Go will need GOMAXPROCS to be an integer.

Instead, use Uber’s automaxprocs, which automatically reads the cgroup CPU limit and sets GOMAXPROCS accordingly:

import _ "go.uber.org/automaxprocs"

Risks

CPU throttling if Go tries to use more CPUs than have been assigned.
Non-deterministic performance when multiple Go processes are vying for limited CPU.

Recommendations

Always include resources.limits.cpu in your pod spec.
Auto-adjust safely with automaxprocs.
Do not hand-tune except when absolutely necessary.

Can a Container Be Restarted Without Resource Limits?

Yes — a container can recover even without memory or CPU limits, as Kubernetes resumes containers due to several reasons:

Process crashes (non-zero exit code)
OOMKilled by the kernel
Failed liveness/readiness probes
Node or kubelet failures

Even if you do not set limits, a container still can potentially be OOM Killed by the kernel if the node is low on memory. Kubernetes will catch this and will restart the container (if restartPolicy: Always).

Use this command to debug:

kubectl describe pod <pod-name>

Look for:

Last State: OOMKilled
Exit Code
Reason

Final Thoughts

By using GOMEMLIMIT and GOMAXPROCS in Kubernetes configuration, you can readily improve the stability and performance associated with your Go programs. Misusing them or not using them at all can lead to performance hotspots, program crashes, or uncontrolled use of system resources. Couple these settings with proper resource limits and observability tools to support seamless operations in production environments.

✅ Dynamic Captcha Loader – Online Tool

Thu, 15 May 2025 09:51:50 +0000

This tool allows you to perform integration tests for captcha challenge verification on the server side.

It currently supports Google, Cloudflare, and hCaptcha.

tool: https://captcha.javad.dev/
repo: https://github.com/ja7ad/captcha

Implement Your Own Request Middleware for Go HTTP Server

Sun, 04 May 2025 23:33:56 +0000

I believed this topic is a lot in the internet but I want to write it anyway, because documenting your own learning journey and share it to the world is good right?

Request middleware performs some specific function on the HTTP request or response at a specific stage in the HTTP pipeline before the business logic / app handler.

Currently middleware is a common term but in different programming language or framework sometimes it called filter. For illustration could be like this

As you can see, middleware could be layered for more than one before hitting app handler or business logic then later it will return the response. HTTP Request comes in to first layer or middleware, check the necessary and if all conditions are passed then it allowed to continue the journey. If failed, it could also returned the failed response anyway.

Basic Middleware

Let say we have simple HTTP API server

func rootHandler() http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
resp := defaultResponse{
Status:      "OK",
Description: "Success",
}

j, _ := json.Marshal(resp)
w.Header().Add("Content-Type", "application/json")
w.Write(j)
})
}

func main() {
mux := http.NewServeMux()

mux.Handle("GET /", rootHandler())

s := &http.Server{
Addr:    ":8080",
Handler: mux,
}

// ...
}

if we run the program go run main.go and visit http://localhost:8080 it will return 200 success with JSON response:

{
  "status": "OK",
  "description": "Success"
}

Now lets create our first middleware. Our middleware is to write a simple log that indicating the request is passing through. The middleware should be a function like this

func logMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
log.Print("Executing logMiddleware")
next.ServeHTTP(w, r)
})
}

Then we will modify the mux handler to use the middleware

func main() {
mux := http.NewServeMux()
    mux.Handle("/", logMiddleware(rootHandler()))
    // ...
}

The result is when we’re visiting the API, it also wrote the log that already specified in the middleware logic.

Adding More Middleware

Interesting. Now try to add more middleware. This time we will check if the API request header contains x-signature, if not exists then we will return error.

Lets create the middleware function

func requestSignatureMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
log.Print("Executing requestSignatureMiddleware")
h := r.Header.Get("x-signature")
if h == "" {
resp := errorResponse{
Status:  http.StatusUnauthorized,
Error:   "INVALID_MISSING_SIGNATURE",
Message: "missing request signature",
}

j, _ := json.Marshal(resp)
w.Header().Add("Content-Type", "application/json")
w.WriteHeader(http.StatusUnauthorized)
w.Write(j)
return
}
next.ServeHTTP(w, r)
})
}

We want to call logMiddleware first then continue to requestSignatureMiddleware. Our mux handler would be look like this now

func main() {
mux := http.NewServeMux()
    mux.Handle("/", logMiddleware(requestSignatureMiddleware(rootHandler())))
    // ...
}

Here’s the result of the combined middlewares

First request without x-signature header will returned 401 HTTP status
Second request with additional x-signature header passed middleware logic and returned 200 HTTP status.

Cleaning Up

You may notice that our mux handler with multiple middlewares is little bit messy because it is calling function into function. What if we have many middlewares?

logMiddleware(requestSignatureMiddleware(authMiddleware(rateLimitMiddleware(rootHandler)))))

Hard to see.

Here’s what we can do, create a chain function to loop all middleware functions. You can named the function whatever you want.

// Middleware type for cleaner middleware chaining
type Middleware func(http.Handler) http.Handler

// Chain creates a single middleware from multiple middlewares
func Chain(middlewares ...Middleware) Middleware {
return func(next http.Handler) http.Handler {
for i := len(middlewares) - 1; i >= 0; i-- {
next = middlewares[i](next)
}
return next
}
}

Initiate the Chain with our middlewares and finally call it in our mux handler.

func main() {
mux := http.NewServeMux()

// Create a chain of middlewares
middlewareChain := Chain(
func(next http.Handler) http.Handler { return logMiddleware(next) },
func(next http.Handler) http.Handler { return requestSignatureMiddleware(next) },
// Add more middlewares here as needed
)

mux.Handle("GET /", middlewareChain(rootHandler()))
    // ...
}

Now it’s more manageable and it will still got same result as before.

So here’s the full code of this experiment https://gist.github.com/didikz/98de868f20887285f5aabc80f4dddcfa

Happy coding!

Coder Legion - Recent posts tagged golang

A Weekend Project With Docker Agent: Four Agents, Two Config Files, One Permissions Trap

What Docker Agent is

The team

The whole team is one file

The same team in HCL

Guardrails live next to the agents

Testing the guardrails without an API key

The permissions trap

Other rough edges

Try it

My Voice Is Code: How 2 Years as a Mute Freelance Go Developer Made Me an Async-First Expert

My Voice Is Code: How Being Mute Made Me The Best Async Dev You Will Hire

1. Silence Became My Stack

2. What 2 Years As Freelance Go Taught Me

3. Why Async First Teams Love Me

4. Open To Work: Remote Async Teams

5. The Invitation

Deploying a Production-Ready Go Scraper to Kubernetes with Prometheus: The Complete Implementation

Production-Ready Go Scraper with Prometheus - Complete Implementation Building a scraper

How to Build an MCP Server in Golang Using the Official MCP SDK

ForgeZero: What Happens When Someone Finally Stops Forgiving Your Build System

The Thesis, Stated Plainly

The Pipeline as a Chain of Owned Transformations

Who This Was Actually Built For

Cache Identity: The Part Everyone Gets Wrong

Two Hashes, One Honest Boundary

Below the Go Standard Library: The Discovery Layer

io_uring, Used Honestly

Linking, Scheduling, and the False-Sharing Detail Most Projects Never Bother With

Gloria: The Language That Refuses to Hide Anything

Security as a Neighbor, Not a Costume

The Redis Case Study, Read Correctly

Cross-Platform Without Pretending Every Platform Is the Same

The Installer Nobody Notices Until It Breaks

What ForgeZero Deliberately Doesn't Do — And Why That's Worth Trusting

Where This Actually Leaves You

GoGraph updates, Providing Structural Awareness to AI Coding Agents in Go.

Fighting Build-System Complexity: Alex Voste on Systems Programming, Performance and ForgeZero

From Systems Engineering to ForgeZero: Alex Voste on Performance, Build Systems, Assembly and the Fight Against Overhead

1. From Systems Engineering to ForgeZero

2. The Problem With Modern Build Systems

3. Why Build Another Build System?

4. Why Go and Assembly?

5. Where Does the Performance Difference Come From?

6. Building for Low-Level Developers

7. Open Source and Building in Public

8. Performance vs. Complexity

9. AI and Low-Level Engineering

10. What Comes Next for ForgeZero?

11. The Engineer Behind the Optimization

About Alex Voste

ForgeZero

Final Thoughts

Gnat - Self-Hosted Analytics

No third party, no phoning home

One binary, zero bloat

Real analytical depth

Built for the agent era

Where it's at

Ninja is Slow. We Built a Build System in Go That Outperforms It by 39x on a Quarter-Million Tasks

ForgeZero 2.0: We Built a Build System 39x Faster Than Ninja

The Problem Everyone Ignores

What ForgeZero Actually Is

The Benchmark That Broke Ninja's Narrative

Why This Demolishes Every Competitor

1. Architecture: One Process, Infinite Goroutines

2. Zero Allocations in Hot Paths

3. Memory-Resident Object Cache

4. BLAKE3 Instead of SHA-256

5. Custom Lock-Free Scheduler

What's New in ForgeZero 2.0 (v5.3.0)

Embedded x86 Assembler

ISO Image Generation

Three Cache Modes

Inline Bash Scripts

Rollback Support

Rewritten Scheduler

Rewritten Config System

Cross-Platform Reality