DEV Community: Rafael Pazini

Meu Claude tem memória agora: e foi mais simples do que parece

Rafael Pazini — Tue, 07 Apr 2026 02:18:48 +0000

TL;DR: Claude Code tem três camadas de memória. A maioria dos devs usa só uma. Li o artigo do Artem Zhutov que explica as três, mas ao invés de implementar tudo do zero, descobri que já tinha 90% do sistema montado. Só faltava conectar as peças. Aqui está exatamente o que eu fiz.

Eu estava no meio de uma sessão de code review quando o Claude me perguntou pela terceira vez na semana se eu preferia testify/mock ou uber-go/mock.

Eu já tinha corrigido isso. Duas vezes. Em sessões diferentes.

O problema não era o Claude. Era eu, tratando ele como uma ferramenta que reseta toda vez, em vez de um colaborador que aprende. Então fui entender melhor como funciona a memória do Claude Code. E aí encontrei o artigo do Artem, que documentou algo que a maioria dos devs não sabe que existe.

As três camadas de memória

Camada 1: CLAUDE.md

Você escreve, você mantém. Regras fixas, contexto do projeto, stack, pessoas-chave. O problema: cresce rápido, fica defasado mais rápido ainda. O meu tinha chegado em 180 linhas. O Claude claramente não estava lendo por completo.

Camada 2: Auto-memory

O Claude escreve suas próprias preferências. Você corrige uma vez, ele salva em ~/.claude/memory/ e carrega nas sessões seguintes. Cada arquivo captura um padrão ou preferência específica.

Para ativar:

claude        # abre o Claude Code
/memory       # abre o menu de configurações de memória
              # -> toggle "Auto-memory" ON

Camada 3: Auto-dream

Roda em background a cada 24h. Lê os transcripts de conversa locais, consolida memórias, remove as defasadas, converte datas relativas em absolutas. É um VACUUM no banco de dados do seu agente. Você ativa e esquece.

Para ativar: mesmo menu /memory, toggle "Auto-dream" ON.

O auto-dream não exige configuração. Roda à meia-noite, limpa o que ficou defasado, e na manhã seguinte o contexto está mais preciso.

O que o auto-dream faz na prática

Aqui está o que acontece quando o auto-dream roda.

Ele lê os arquivos de memória do projeto em ~/.claude/projects/<projeto>/memory/ e faz quatro coisas:

Mescla entradas redundantes: se você corrigiu o mesmo comportamento duas vezes em sessões diferentes, o auto-dream consolida as duas notas em uma.
Remove contexto defasado: se você finalizou uma migração, a memória "migração em andamento" some. O Claude para de mencionar algo que já não existe.
Converte datas relativas em absolutas: "ontem decidimos X" vira "2026-04-05: decidimos X". Fundamental para que as memórias façam sentido depois de semanas.
Reorganiza para facilitar a busca: entradas soltas viram arquivos organizados por tema.

O efeito prático: cada sessão começa com um contexto mais limpo. Sem aquele ruído acumulado de decisões antigas que já foram revertidas, ou de contexto de projeto que mudou há duas semanas.

Um exemplo concreto: imagine que você está migrando o hash de senhas de MD5 para bcrypt. Durante três sessões, o Claude carrega o contexto "migration in progress: replace MD5 with bcrypt across user service". Na quarta sessão, você finaliza e faz o merge. O auto-dream lê que a tarefa foi concluída e substitui a memória por "bcrypt migration completed 2026-04-03, MD5 fully removed from user service". Na quinta sessão, o Claude já sabe que a migração terminou, sem você precisar mencionar.

Gotcha: O auto-dream tem dois gatilhos: tempo suficiente passado e sessões suficientes acumuladas. Ele não roda depois de uma única sessão longa, nem depois de dez sessões rápidas em duas horas. Se você quiser disparar manualmente, use o comando /dream no Claude Code.

O que eu já tinha e não sabia

Aqui está a parte que o artigo do Artem não cobre, porque é específica da minha configuração.

Eu já tinha um diretório ~/.claude/rules/common/ com 11 arquivos organizados por tema:

~/.claude/rules/common/
├── coding-style.md         <- imutabilidade, organização de arquivos
├── testing.md              <- TDD, cobertura, tipos de teste
├── git-workflow.md         <- formato de commit, processo de PR
├── security.md             <- checklist de segurança
├── performance.md          <- seleção de modelo, contexto
├── patterns.md             <- Repository Pattern, API response format
├── agents.md               <- orquestração de agentes
├── hooks.md                <- tipos de hook, boas práticas de auto-accept
├── open-pr.md              <- checklist de PR, sempre draft
├── development-workflow.md
└── always-works.md         <- TDD + coverage gate + verificação

Esses arquivos já eram minha Camada 1, só que melhor organizada que um CLAUDE.md monolítico. Cada sessão carregava o contexto relevante com alta coesão e baixo acoplamento.

O que estava faltando: uma forma de alimentar esses arquivos com o que acontecia nas sessões, sem fazer isso manualmente.

A solução: o `/retro` simplificado

O Artem propõe um skill de retrospectiva que cria arquivos novos de memória a cada sessão. O que eu fiz foi diferente: adaptei o /retro para classificar o que aprendeu na sessão e decidir onde salva. Memória de projeto ou regras globais que já existem.

O skill em ~/.claude/skills/retro/SKILL.md (estrutura simplificada):

# Session Retrospective

Reviews the session and does two things:
1. Proposes memory updates (corrections, preferences, decisions)
2. Exports a session summary to the Obsidian vault

## Step 1: Extract signals

Categorize findings:
- Corrections: what the user corrected and what they wanted instead
- Confirmed patterns: what worked on the first try
- Redos: what had to be redone and why
- New decisions: architecture or workflow choices

## Step 2: Classify scope

For each signal, decide where to save:

Project memory: specific to this codebase
-> ~/.claude/projects/<project>/memory/

Global rule: applies to ALL projects
-> append to ~/.claude/rules/common/<relevant-file>.md
-> never create a new file. Only update existing ones.

## Step 3: Present and wait for approval

Show findings table and wait for approval before writing.

| # | Type       | Finding                                   | Proposed action | Scope                |
|---|------------|-------------------------------------------|-----------------|----------------------|
| 1 | correction | Used testify/mock instead of uber-go/mock | Update rule     | global: testing.md   |
| 2 | decision   | Chose Redis Streams for queues            | Create memory   | project: minha-api   |
| 3 | confirmed  | Commit format was correct                 | No action       | -                    |

## Step 4: Export session to vault

Writes to:
~/Documents/rflpazini/sessions/YYYY-MM-DD-<project>-<topic>.md

O ponto central: ao invés de criar uma nova camada de arquivos, o /retro alimenta o knowledge base que já existe. Correções de comportamento global vão para testing.md, coding-style.md ou git-workflow.md, dependendo do assunto. Decisões específicas vão para a memória do projeto.

A observabilidade pelo Obsidian

Aqui entra o obsidian-mind: um projeto open-source que transforma seu vault Obsidian num segundo cérebro para o Claude Code, com CLAUDE.md configurado, hooks, slash commands e uma estrutura pensada para capturar contexto de trabalho.

Ao setup padrão eu adicionei três coisas:

1. Pasta sessions/ para histórico cross-project

Cada sessão vira um arquivo com: objetivo, o que foi feito, decisões, aprendizados, próximos passos. O /retro escreve isso automaticamente. Exemplo de como fica:

---
title: "Session: minha-api - kafka-consumer"
date: 2026-04-05
tags: [session, minha-api]
project: "[[minha-api]]"
---

## Goal
Implementar o consumer Kafka async com DLQ imediato, sem retry.

## What Got Done
- Consumer async configurado com ack-mode RECORD
- DLQ publishing manual implementado no error handler
- Testes de integração passando

## Decisions Made
- AbortPolicy + DLQ imediato: CallerRunsPolicy bloqueava o poll thread do Kafka
- ack-mode RECORD, não BATCH: BATCH commita offsets antes das tasks completarem

## Learnings
- Container-level error handler e DLQ manual ativos ao mesmo tempo causam duplicação
- Testar com consumer group real antes de fazer PR

## Next Steps
- [ ] Revisar configuração de timeout do executor
- [ ] Abrir PR após code review

2. Symlink das memórias de projeto no vault

#!/bin/bash
# ~/.claude/scripts/sync-memories-to-vault.sh
# Cria symlinks de ~/.claude/projects/*/memory/ para o vault Obsidian
# Roda automaticamente após o /retro

VAULT_MEMORY_DIR="$HOME/Library/Mobile Documents/iCloud~md~obsidian/Documents/rflpazini/claude/memories"
CLAUDE_PROJECTS="$HOME/.claude/projects"

mkdir -p "$VAULT_MEMORY_DIR"

clean_name() {
  local raw="$1"
  case "$raw" in
    *-minha-api*)    echo "minha-api" ;;
    *-outro-projeto*) echo "outro-projeto" ;;
    *-obsidian-mind*) echo "obsidian-mind" ;;
    *)
      echo "$raw" \
        | sed 's/^-Users-seuusuario-//' \
        | sed 's/^Documents-Development-//' \
        | tr '[:upper:]' '[:lower:]' \
        | sed 's/^-//'
      ;;
  esac
}

created=0
skipped=0

for memory_dir in "$CLAUDE_PROJECTS"/*/memory; do
  [ -d "$memory_dir" ] || continue
  project_dir=$(dirname "$memory_dir" | xargs basename)
  name=$(clean_name "$project_dir")
  link_path="$VAULT_MEMORY_DIR/$name"

  if [ -L "$link_path" ] || [ -d "$link_path" ]; then
    skipped=$((skipped + 1))
  else
    ln -s "$memory_dir" "$link_path"
    created=$((created + 1))
  fi
done

echo "done. created=$created skipped=$skipped"

Cada memória de projeto aparece como arquivo navegável no Obsidian. Você vê, edita ou apaga direto pelo painel lateral, sem precisar abrir o terminal.

3. Base view Sessions.base

Uma view Obsidian que lista todas as sessões por projeto, ordenadas por data. Quando começo uma sessão nova, abro essa view e vejo em 10 segundos o contexto da última vez que trabalhei naquele projeto.

O que não implementei (e por quê)

O artigo do Artem sugere mais coisas: QMD para busca semântica, dashboards por área de vida, session auto-export hooks, LLM Wiki.

Não implementei nenhuma. O vault tinha 50 arquivos no momento. QMD resolve um problema de busca que ainda não existe. Dashboards adicionam fricção de manutenção antes de gerar valor.

A regra que usei: cada adição foi avaliada pela fricção que criava, não pelo potencial teórico. Se não resolvia um problema que eu tinha hoje, ficou de fora.

Gotcha: Auto-memory é estritamente scoped por projeto. Não existe auto-memory global. Preferências que devem valer em todos os projetos precisam ir para ~/.claude/rules/common/, via /retro ou manualmente. O artigo original não deixa isso claro.

Como fica o loop na prática

Segunda-feira de manhã. Abro o terminal, claude, começo a trabalhar.

O hook SessionStart injeta automaticamente: data de hoje, objetivos atuais, projetos ativos, listagem de arquivos do vault. Não preciso explicar contexto nenhum.

Trabalho a sessão. No final: /retro.

O Claude monta a tabela de achados com escopo sugerido e aguarda minha aprovação. Aprovo: ele faz append em testing.md para a regra de mock, cria arquivo em ~/.claude/projects/minha-api/memory/ para o contexto específico, e escreve o resumo em rflpazini/sessions/.

Encerro o terminal. De noite, o auto-dream consolida, remove o que ficou defasado.

Na manhã seguinte, o Claude começa sabendo exatamente onde paramos.

E esse é o resultado no Obsidian:

Como começar

Mínimo viável (30 minutos):

Instale o obsidian-mind ou abra o Claude Code dentro do seu vault Obsidian existente
Ative auto-memory: claude -> /memory -> toggle ON
Ative auto-dream: mesmo menu -> toggle ON
Execute /retro ao final das próximas 3 sessões

Para o setup completo:

Organize seu CLAUDE.md em arquivos separados por tema em ~/.claude/rules/common/
Crie o skill /retro com a estrutura acima
Crie a pasta sessions/ no vault para histórico cross-project
Configure o script sync-memories-to-vault.sh para visibilidade das memórias no Obsidian

O Claude não vai parar de errar do dia para a noite. Mas cada correção que você faz uma vez não vai precisar ser repetida. Esse é o investimento: tempo decrescente de alinhamento, qualidade crescente de colaboração.

Três semanas depois de configurar isso, as sessões começam sem aqueles 15 minutos de "deixa eu te explicar o contexto". O Claude chega sabendo.

Crédito ao Artem Zhutov pela documentação das três camadas. O que eu fiz foi simplificar a implementação aproveitando o que já existia.

e também ao Brenno Ferrari pelo obsidian-mind

Testa, roda o /retro nas próximas sessões, e me conta o que apareceu na tabela de achados.

Nos próximos dias, vou publicar as skills que utilizo no github :)

Docker Compose + tmpfs: Armazenamento efêmero que sua aplicação

Rafael Pazini — Tue, 10 Mar 2026 12:26:20 +0000

Você já parou para pensar onde sua aplicação Go escreve arquivos temporários? /tmp, cache de build, sessões, uploads intermediários... tudo isso vai parar em disco. E disco é lento. Não "lento para 2024" — lento mesmo, comparado com o que podemos fazer.

Existe uma alternativa que a maioria dos devs ignora: tmpfs. Um filesystem que mora na RAM, some quando o container reinicia, e é absurdamente rápido. É tipo aquele colega que resolve o problema na hora, mas não te manda e-mail depois — eficiente e efêmero.

Vamos ver o que muda na prática e quando faz sentido usar.

Nota: Os exemplos deste artigo usam Go 1.26, lançado em fevereiro de 2026. Uma das novidades dessa versão é o Green Tea GC habilitado por padrão — o que torna a combinação com tmpfs ainda mais poderosa: menos alocações em disco + GC mais eficiente = serviços Go mais rápidos e previsíveis.

O que é tmpfs, afinal?

Tmpfs é um filesystem temporário que reside inteiramente na memória RAM:

⚡ Ultra-rápido — velocidade de RAM, não de disco
🔒 Seguro — dados não persistem entre restarts
🧹 Auto-limpante — some sozinho quando o container para

Parece mágica, mas é só o SO sendo inteligente. Linux já tem suporte nativo há décadas; o Docker Compose apenas expõe isso de forma limpa.

Configuração básica

A forma mais simples de usar:

services:
  app:
    image: myapp-go
    tmpfs:
      - /tmp
      - /app/cache
      - /var/run

Com limite de tamanho (o que você definitivamente deveria fazer em produção):

services:
  app:
    image: myapp-go
    tmpfs:
      - /tmp:size=100M
      - /app/cache:size=500M
      - /var/run:size=10M

Sem o limite de tamanho, seu tmpfs pode consumir toda a RAM disponível. Isso é o tipo de surpresa que você não quer às 2h da manhã com o PagerDuty tocando.

Configuração avançada

Para quem quer controle fino sobre permissões:

services:
  app:
    image: myapp-go
    tmpfs:
      - type: tmpfs
        target: /tmp
        tmpfs:
          size: 100M
          mode: 1770    # permissões do diretório
          uid: 1000     # usuário dono
          gid: 1000     # grupo dono

Ou usando a sintaxe de volumes (mais verbosa, mas mais explícita):

services:
  app:
    image: myapp-go
    volumes:
      - type: tmpfs
        target: /app/temp
        tmpfs:
          size: 200000000  # 200MB em bytes

Casos de uso com Go: onde isso realmente brilha

1. Cache de build Go

Quem já esperou o go build rodar dentro de um container sabe a dor. O cache de compilação do Go pode ser colocado em tmpfs para acelerar builds em CI:

services:
  builder:
    image: golang:1.26
    working_dir: /app
    volumes:
      - .:/app
      - type: tmpfs
        target: /root/.cache/go-build
        tmpfs:
          size: 2G
    command: go build ./...

Aviso: o cache some quando o container para. Para CI eficiente, combine isso com um volume persistente para o cache entre pipelines. Para builds únicos dentro de um job, tmpfs é perfeito.

2. Uploads temporários em APIs Go

Sua API Go recebe arquivos, processa e manda para S3? Não tem sentido escrever em disco se você vai deletar logo depois:

services:
  api:
    image: myapi-go
    tmpfs:
      - /tmp/uploads:size=2G,mode=1770
    environment:
      UPLOAD_DIR: /tmp/uploads
      MAX_UPLOAD_SIZE: 100M

No código Go, basta ler a variável de ambiente:

package main

import (
    "fmt"
    "io"
    "net/http"
    "os"
    "path/filepath"
)

var uploadDir = getEnv("UPLOAD_DIR", "/tmp/uploads")

func getEnv(key, fallback string) string {
    if v := os.Getenv(key); v != "" {
        return v
    }
    return fallback
}

func uploadHandler(w http.ResponseWriter, r *http.Request) {
    if r.Method != http.MethodPost {
        http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
        return
    }

    r.Body = http.MaxBytesReader(w, r.Body, 100<<20) // 100MB max
    if err := r.ParseMultipartForm(32 << 20); err != nil {
        http.Error(w, "file too large", http.StatusBadRequest)
        return
    }

    file, header, err := r.FormFile("file")
    if err != nil {
        http.Error(w, "invalid file", http.StatusBadRequest)
        return
    }
    defer file.Close()

    // Escreve no tmpfs — rápido e sem deixar rastro
    tmpPath := filepath.Join(uploadDir, header.Filename)
    dst, err := os.Create(tmpPath)
    if err != nil {
        http.Error(w, "failed to save file", http.StatusInternalServerError)
        return
    }
    defer func() {
        dst.Close()
        os.Remove(tmpPath) // limpa após processar
    }()

    if _, err = io.Copy(dst, file); err != nil {
        http.Error(w, "failed to write file", http.StatusInternalServerError)
        return
    }

    // Aqui você processaria e mandaria pro S3, por exemplo
    fmt.Fprintf(w, "arquivo %s processado com sucesso", header.Filename)
}

3. Banco de dados para testes

Esse é o meu favorito. Rodar o banco de testes com dados em tmpfs é 3-5x mais rápido que em disco:

services:
  # Banco de testes — rápido, dados não persistem (e não precisam)
  test-db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: test
      POSTGRES_DB: testdb
    tmpfs:
      - /var/lib/postgresql/data:size=1G
    profiles: ["test"]

  # Banco de produção — persistente, como deve ser
  prod-db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    profiles: ["prod"]

volumes:
  postgres_data:

Em Go, seus testes de integração com Testcontainers ou docker compose ficam muito mais ágeis. Se você ainda não usa Testcontainers em Go, dá uma olhada no artigo que escrevi sobre isso — a combinação com tmpfs é poderosa.

4. Segurança: filesystem read-only com exceções tmpfs

Esse padrão é subestimado. Você torna o filesystem inteiro read-only e usa tmpfs apenas para os diretórios que precisam de escrita:

services:
  secure-api:
    image: myapi-go
    read_only: true          # filesystem inteiro somente leitura
    tmpfs:
      - /tmp:size=100M       # escrita permitida aqui
      - /var/run:size=10M
      - /app/cache:size=50M
    volumes:
      - app_logs:/var/log:rw # logs persistentes

Para aplicações Go, isso é excelente. O binário compilado é estático — não precisa escrever em lugar nenhum além dos diretórios que você define explicitamente. É defense-in-depth sem custo nenhum.

Benchmark: vendo a diferença

Quer medir o ganho? Coloca isso no seu compose:

services:
  benchmark:
    image: golang:1.26-alpine
    command: |
      sh -c "
        echo '=== Tmpfs Write Performance ==='
        time dd if=/dev/zero of=/tmp/test bs=1M count=500 conv=fsync

        echo ''
        echo '=== Volume Write Performance ==='
        time dd if=/dev/zero of=/data/test bs=1M count=500 conv=fsync
      "
    tmpfs:
      - /tmp:size=1G
    volumes:
      - benchmark_data:/data

volumes:
  benchmark_data:

Em máquinas típicas de desenvolvimento, tmpfs é 3 a 10x mais rápido que um volume em disco. Em produção com SSDs NVMe, a diferença diminui, mas ainda é significativa para workloads de I/O intenso.

Sizing dinâmico por ambiente

Uma dica que uso nos meus projetos: tamanho de tmpfs configurável por ambiente:

services:
  app:
    image: myapi-go
    tmpfs:
      - /tmp:size=${TMPFS_SIZE:-100M}
      - /app/cache:size=${CACHE_SIZE:-200M}
    deploy:
      resources:
        limits:
          memory: 2G
        reservations:
          memory: 1G

E nos arquivos de ambiente:

# .env.development
TMPFS_SIZE=500M
CACHE_SIZE=1G

# .env.production
TMPFS_SIZE=2G
CACHE_SIZE=4G

# .env.test
TMPFS_SIZE=256M
CACHE_SIZE=512M

Isso é especialmente útil quando você tem a mesma stack rodando em máquinas com capacidades de RAM diferentes — CI com 8GB, produção com 32GB, máquina local com 16GB.

Monitorando o uso

Não vai querer descobrir que o tmpfs estourou em produção. Monitore:

# Verificar uso de tmpfs em um container específico
docker compose exec app df -h | grep tmpfs

# Monitorar todos os containers
docker compose ps -q | xargs -I {} docker exec {} df -h 2>/dev/null | grep tmpfs

# Ver impacto na memória do sistema
docker stats --no-stream

No Go, você pode expor uma métrica de uso de /tmp diretamente no seu endpoint de health check:

package health

import (
    "encoding/json"
    "net/http"
    "syscall"
)

type DiskStats struct {
    Total     uint64 `json:"total_bytes"`
    Free      uint64 `json:"free_bytes"`
    Used      uint64 `json:"used_bytes"`
    UsedPct   float64 `json:"used_pct"`
}

func TmpfsStats() (*DiskStats, error) {
    var stat syscall.Statfs_t
    if err := syscall.Statfs("/tmp", &stat); err != nil {
        return nil, err
    }

    total := stat.Blocks * uint64(stat.Bsize)
    free := stat.Bfree * uint64(stat.Bsize)
    used := total - free

    return &DiskStats{
        Total:   total,
        Free:    free,
        Used:    used,
        UsedPct: float64(used) / float64(total) * 100,
    }, nil
}

func HealthHandler(w http.ResponseWriter, r *http.Request) {
    stats, err := TmpfsStats()
    if err != nil {
        http.Error(w, "failed to check tmpfs", http.StatusInternalServerError)
        return
    }

    status := "ok"
    if stats.UsedPct > 85 {
        status = "warning"
    }

    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(map[string]any{
        "status": status,
        "tmpfs":  stats,
    })
}

Exemplos do mundo real

Teoria é legal, mas vamos ver como tmpfs se encaixa em cenários que você provavelmente já viveu — ou vai viver.

LocalStack + tmpfs: desenvolvimento AWS sem custo e sem lentidão

Se você já configurou o LocalStack para emular S3, DynamoDB, SQS localmente (tem um artigo completo sobre isso aqui), sabe que o DynamoDB e o SQS escrevem dados temporários em disco durante os testes. Em ambiente de dev local, esses dados não precisam persistir entre restarts. É desperdício puro.

A combinação tmpfs + LocalStack elimina esse overhead e faz o ambiente local rodar muito mais próximo da velocidade real:

services:
  localstack:
    image: localstack/localstack:latest
    container_name: localstack
    ports:
      - "4566:4566"
    environment:
      - SERVICES=dynamodb,sqs,s3
      - DEBUG=0
    # Dados do LocalStack não precisam sobreviver ao restart em dev
    tmpfs:
      - /var/lib/localstack:size=1G
      - /tmp/localstack:size=512M

  # Sua API Go apontando para o LocalStack
  api:
    build: .
    ports:
      - "8080:8080"
    environment:
      AWS_ACCESS_KEY_ID: test
      AWS_SECRET_ACCESS_KEY: test
      AWS_ENDPOINT: http://localstack:4566
    # Uploads intermediários antes de mandar para o S3 "local"
    tmpfs:
      - /tmp/uploads:size=512M,mode=1770
    depends_on:
      - localstack

No código Go, a lógica do worker que consome a fila SQS e processa arquivos fica mais enxuta quando você sabe que o diretório temporário é RAM:

package worker

import (
    "context"
    "encoding/json"
    "fmt"
    "log"
    "os"
    "path/filepath"

    "github.com/aws/aws-sdk-go-v2/service/sqs"
)

type UploadMessage struct {
    UserID   string `json:"user_id"`
    Filename string `json:"filename"`
    Size     int64  `json:"size"`
}

func ProcessUploadQueue(ctx context.Context, sqsClient *sqs.Client, queueURL, uploadDir string) {
    for {
        out, err := sqsClient.ReceiveMessage(ctx, &sqs.ReceiveMessageInput{
            QueueUrl:            &queueURL,
            MaxNumberOfMessages: 10,
            WaitTimeSeconds:     5,
        })
        if err != nil {
            log.Printf("receive error: %v", err)
            continue
        }

        for _, msg := range out.Messages {
            var payload UploadMessage
            if err := json.Unmarshal([]byte(*msg.Body), &payload); err != nil {
                log.Printf("unmarshal error: %v", err)
                continue
            }

            // Arquivo temporário no tmpfs — processamento em RAM
            tmpPath := filepath.Join(uploadDir, fmt.Sprintf("%s_%s", payload.UserID, payload.Filename))

            // Processa (redimensiona, valida, converte)
            if err := processFile(ctx, tmpPath, payload); err != nil {
                log.Printf("process error: %v", err)
                continue
            }

            // Limpa — no tmpfs isso é instantâneo
            os.Remove(tmpPath)

            // Delete da fila só após processar com sucesso
            sqsClient.DeleteMessage(ctx, &sqs.DeleteMessageInput{
                QueueUrl:      &queueURL,
                ReceiptHandle: msg.ReceiptHandle,
            })
        }
    }
}

func processFile(ctx context.Context, path string, msg UploadMessage) error {
    // Aqui: validar, converter, enviar pro S3 real ou LocalStack
    log.Printf("processing %s for user %s (%d bytes)", msg.Filename, msg.UserID, msg.Size)
    return nil
}

O ganho é duplo: o LocalStack inicia mais rápido (sem I/O de disco para inicializar os dados), e os arquivos temporários do seu worker nunca tocam o disco da máquina.

Imagens scratch + tmpfs: a combinação mais segura que você pode fazer

No artigo sobre imagens Docker para Go, mostrei que usar scratch como imagem final chega a ~21MB — menos que alpine (~30MB) e muito menos que a imagem com SDK (~251MB). O que não mencionei lá é que scratch e read_only: true são feitos um para o outro, e tmpfs é o elo que faz tudo funcionar.

O problema de usar scratch com read_only: true é que a aplicação não consegue escrever em lugar nenhum — nem em /tmp. Sem tmpfs, você precisaria ou relaxar o read_only ou montar volumes, o que aumenta a superfície de ataque. Com tmpfs, você tem o melhor dos dois mundos:

services:
  api:
    build:
      context: .
      dockerfile: Dockerfile  # multi-stage com scratch
    read_only: true            # filesystem inteiro imutável
    tmpfs:
      - /tmp:size=256M         # única área gravável — e ainda assim efêmera
      - /var/run:size=10M
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL

E o Dockerfile que casa com isso (multi-stage com scratch, como discutido no artigo de imagens):

# syntax=docker/dockerfile:1

# Build: compila com Go 1.26
FROM golang:1.26-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
# CGO_ENABLED=0 garante binário estático — requisito para scratch
RUN CGO_ENABLED=0 GOOS=linux go build \
    -ldflags="-s -w" \
    -o /app/server ./cmd/server

# Final: scratch + tmpfs = imagem mínima + filesystem imutável
FROM scratch
COPY --from=builder /app/server /server
# /tmp será montado como tmpfs pelo docker compose — não precisa existir na imagem
EXPOSE 8080
ENTRYPOINT ["/server"]

A combinação scratch + read_only: true + tmpfs resulta em:

Imagem final de ~21MB (só o binário Go)
Zero pacotes extras para explorar
Filesystem completamente imutável em produção
Única área gravável (/tmp) existe na RAM e some com o container

É o padrão mais hardened que você consegue com Go e Docker hoje, sem abrir mão de nenhuma funcionalidade.

MCP server + tmpfs: cache de respostas de API sem persistência

Se você já brincou com MCP servers em Docker, sabe que eles ficam intermediando chamadas entre o Claude (ou qualquer LLM) e APIs externas. Essas chamadas muitas vezes retornam payloads grandes de JSON — respostas de APIs, documentações de Swagger, listas de recursos — que são processados uma vez e descartados.

Salvar isso em disco é desperdício. Salvar no tmpfs faz sentido:

services:
  mcp-gateway:
    image: rflpazini/mcp-api-gateway
    environment:
      API_1_NAME: internal-api
      API_1_SWAGGER_URL: https://api.exemplo.com/swagger.json
      API_1_BASE_URL: https://api.exemplo.com/v1
      # Diz pro gateway onde cachear as respostas temporárias
      CACHE_DIR: /tmp/mcp-cache
      RESPONSE_CACHE_TTL: 30s
    tmpfs:
      # Cache de respostas — não precisa sobreviver a restart
      - /tmp/mcp-cache:size=200M,mode=1770
      # Schemas Swagger baixados para parsing
      - /tmp/schemas:size=50M

  # Seu servidor Go que o MCP chama
  internal-api:
    build: .
    read_only: true
    tmpfs:
      - /tmp:size=128M
    environment:
      PORT: "8080"

Se você quiser ir além e implementar um cache de respostas no próprio servidor Go que o MCP gateway chama, fica assim:

package cache

import (
    "crypto/sha256"
    "encoding/json"
    "fmt"
    "os"
    "path/filepath"
    "time"
)

type Entry struct {
    Data      any       `json:"data"`
    ExpiresAt time.Time `json:"expires_at"`
}

// FileCache é um cache simples em tmpfs.
// Como é tmpfs, não há custo de I/O — é literalmente memória.
type FileCache struct {
    dir string
    ttl time.Duration
}

func New(dir string, ttl time.Duration) (*FileCache, error) {
    if err := os.MkdirAll(dir, 0o750); err != nil {
        return nil, fmt.Errorf("cache dir: %w", err)
    }
    return &FileCache{dir: dir, ttl: ttl}, nil
}

func (c *FileCache) key(resource string) string {
    h := sha256.Sum256([]byte(resource))
    return filepath.Join(c.dir, fmt.Sprintf("%x.json", h))
}

func (c *FileCache) Get(resource string, dest any) bool {
    path := c.key(resource)
    data, err := os.ReadFile(path)
    if err != nil {
        return false
    }

    var entry Entry
    if err := json.Unmarshal(data, &entry); err != nil {
        return false
    }

    if time.Now().After(entry.ExpiresAt) {
        os.Remove(path) // limpa expirado
        return false
    }

    b, _ := json.Marshal(entry.Data)
    return json.Unmarshal(b, dest) == nil
}

func (c *FileCache) Set(resource string, data any) error {
    entry := Entry{
        Data:      data,
        ExpiresAt: time.Now().Add(c.ttl),
    }

    b, err := json.Marshal(entry)
    if err != nil {
        return err
    }

    // WriteFile em tmpfs = write em RAM. Sem syscall de disco.
    return os.WriteFile(c.key(resource), b, 0o600)
}

A beleza desse padrão é que você tem um cache com TTL que:

Não precisa de Redis para casos simples
Não polui o disco com dados temporários
Morre junto com o container — sem estado residual
É tão rápido quanto acessar memória

Para um MCP gateway que precisa cachear respostas de API por 30 segundos antes de refazer a chamada, isso é mais do que suficiente.

Quando NÃO usar tmpfs

Vamos ser honestos: tmpfs não é bala de prata.

Não use quando:

Os dados precisam sobreviver a um restart (sessões de usuário em produção, por exemplo)
Você tem pouca RAM e workloads com uso intenso de memória concorrente
Os arquivos temporários são gigantes (acima de 20-30% da RAM disponível)
Você precisa de persistência entre deploys no mesmo host

Use sem medo quando:

Dados temporários de processamento (uploads, conversões, transformações)
Cache de compilação em CI
Bancos de dados de teste
Sessões de curta duração que não precisam sobreviver a restarts
Qualquer coisa que você jogaria fora de qualquer jeito

O impacto real no dia a dia

Combinado com boas práticas que já falei em outros artigos — como imagens Docker otimizadas para Go e tuning de performance — tmpfs fecha um gap importante: I/O de disco como gargalo.

Para pipelines de CI/CD, a diferença é imediata. Para APIs Go que processam arquivos, é a diferença entre latência aceitável e latência excelente. Para testes de integração, é o que separa um suite de 5 minutos de um de 15 minutos.

Vale a pena?

Sim. E é uma das mudanças mais fáceis de implementar com impacto real.

Não exige mudança de código. Não exige nova dependência. É um bloco de 3 linhas no seu compose.yml que pode te poupar memória de disco, acelerar I/O e ainda melhorar a postura de segurança do serviço.

Se você já usa Docker Compose no dia a dia (e se escreve Go em 2026, provavelmente usa), isso é a otimização de menor esforço com maior retorno que você pode fazer hoje.

Experimenta, mede com docker stats, e me conta o que você encontrou.

Docker Compose para Agentes de IA: O que realmente mudou (e o que você precisa saber agora)

Rafael Pazini — Tue, 03 Mar 2026 14:12:27 +0000

Se você acompanha o ecossistema Docker, 2025 foi o ano em que eles deixaram de ser "só a ferramenta de containerização" e viraram plataforma de IA de verdade. E o que começou como experimento virou padrão com uma velocidade impressionante — tipo aquele colega que vai a uma conferência e volta querendo reescrever tudo em Rust.

O ponto central de tudo isso é simples: modelos de IA agora são cidadãos de primeira classe no seu compose.yaml. Mesma sintaxe, mesma CLI, mesmo pipeline que você já usa para subir Postgres e Redis. A diferença é que agora o Qwen ou o Gemma também sobem junto.

Vamos ver o que realmente funciona em fevereiro de 2026 e o que você deveria estar usando.

O que mudou no Compose

O artigo de referência estava certo no espírito, mas a sintaxe evoluiu. O bloco provider.type: model com imagens Docker Hub genéricas não é a forma atual. Isso foi simplificado.

A sintaxe correta hoje usa o campo model dentro do bloco models para referenciar o artefato OCI direto do Docker Hub, sem a estrutura aninhada de provider:

models:
  llm:
    model: ai/qwen2.5        # artefato OCI do Docker Hub — isso que você puxa
    context_size: 4096
  embeddings:
    model: ai/all-minilm
    context_size: 2048
    runtime_flags:
      - "--embeddings"       # obrigatório para modelos de embedding

services:
  api:
    build: ./api
    models:
      llm:
        endpoint_var: LLM_URL       # Compose injeta a URL do Model Runner aqui
        model_var: LLM_MODEL_NAME
      embeddings:
        endpoint_var: EMBEDDING_URL
        model_var: EMBEDDING_MODEL_NAME

  vector-db:
    image: qdrant/qdrant:latest
    volumes:
      - ./qdrant:/qdrant/storage

Depois é só:

docker compose up

O Compose puxa os modelos do Docker Hub, sobe o Model Runner, injeta as variáveis de ambiente nos serviços que precisam, e cuida da ordem de inicialização. Você não escreve nenhuma linha de código de infraestrutura.

Versão mínima: Docker Compose 2.38.1+. Se você roda no Linux com Docker Engine (não Desktop), confirme a versão antes. Se roda Docker Desktop, já está coberto.

O ecossistema expandiu bastante

Quando esse assunto surgiu em julho de 2025, os frameworks suportados eram CrewAI, LangGraph e Spring AI. Hoje a lista ficou bem maior. Oficialmente, o repo docker/compose-for-agents tem exemplos funcionando para:

LangGraph (Python)
CrewAI (Python)
Spring AI (Java)
Embabel (JVM)
Vercel AI SDK (Node.js)
Google ADK — esse é novo e é o mais interessante para quem trabalha com raciocínio multi-step

Para Go, o caminho natural ainda é via Langchaingo ou chamadas HTTP diretas — o Compose injeta a URL, o resto é o seu código.

Gordon: o agente que o Docker não estava avisando que ia lançar

Se você não acompanhou, em fevereiro de 2026 o Docker lançou o Gordon — um agente de IA dentro do Docker Desktop (e CLI via docker ai) que tem acesso ao seu ambiente de containers.

O Gordon não é um chatbot. Ele tem shell, CLI do Docker e acesso ao filesystem. Você aponta um problema, aprova as ações, e ele executa. Container saindo com código 137? Gordon inspeciona os logs, identifica o processo que estourou memória, propõe o fix. Você aprova, ele executa.

docker ai "meu container de API está caindo, me ajuda a debugar"

Vale mencionar porque afeta diretamente o fluxo de trabalhar com agentes: o Gordon é construído em cima do cagent, o framework de agentes do Docker, e se integra diretamente com o MCP Gateway. Ou seja, a mesma arquitetura que você define no Compose para seus agentes, o Docker está usando internamente.

Nota de segurança: Em fevereiro de 2026 foi divulgada uma vulnerabilidade onde labels maliciosas em imagens Docker podiam ser usadas para injetar comandos via Gordon → MCP Gateway. Isso foi corrigido na versão 4.50.0+. Se você está em versão anterior, atualize antes de usar Gordon em projetos com imagens de terceiros.

MCP Gateway e MCP Catalog: o que isso muda na prática

Outro componente que o artigo original mencionava de forma superficial e que ficou muito mais relevante: o MCP Gateway, agora open source e GA desde a versão 4.43 do Desktop.

O Gateway é o ponto de controle entre seus agentes e as ferramentas externas. Ele fica no meio do caminho entre o agente (seja LangGraph, CrewAI, ou o próprio Gordon) e os MCP servers (ferramentas como GitHub, MongoDB, Slack, banco de dados, etc.).

No Compose, a integração fica assim:

services:
  my-agent:
    build: ./agent
    models:
      llm:
        endpoint_var: LLM_URL
        model_var: LLM_MODEL_NAME
    environment:
      MCP_GATEWAY_URL: http://mcp-gateway:8811
    depends_on:
      - mcp-gateway
      - llm

  mcp-gateway:
    image: docker/mcp-gateway:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - MCP_SERVERS=github,duckduckgo

models:
  llm:
    model: ai/qwen2.5

O MCP Catalog hoje tem mais de 100 servidores verificados, todos rodando em containers isolados com assinatura criptográfica — muito diferente do padrão anterior de executar via npx ou uvx direto no host.

Model Runner: o que evoluiu desde o lançamento

O Docker Model Runner (DMR) saiu de beta experimental para GA em outubro de 2025. Desde então:

Suporte a Windows com GPU NVIDIA e Qualcomm/ARM
API compatível com OpenAI (você troca o endpoint, o SDK não muda)
API compatível com Anthropic — adicionada recentemente, para quem usa SDKs do Claude
docker model purge para limpar todos os modelos de uma vez
Você pode omitir o prefixo ai/ ao fazer pull: docker model pull qwen2.5 funciona
Downloads retomam se interrompidos — acabou aquela dor de baixar modelos de 4GB na metade

# Antes
docker model pull ai/qwen2.5

# Agora funciona igual
docker model pull qwen2.5

# Endpoint OpenAI-compatible (sem o /engines agora)
curl http://localhost:12434/v1/models

Docker Compose v5 e o Go SDK

Isso ainda não estava no radar quando o artigo original foi escrito: o Compose v5 saiu com um SDK Go oficial que permite controle programático do ambiente multi-container sem depender da CLI.

Para quem escreve ferramentas de plataforma ou pipelines de CI em Go, isso é relevante. Você pode validar, carregar e gerenciar ambientes Compose diretamente no seu código:

import "github.com/compose-spec/compose-go/v2/cli"

// Carrega e valida o compose.yaml programaticamente
options, _ := cli.NewProjectOptions([]string{"compose.yaml"})
project, _ := options.LoadProject(context.Background())

// Valida que os modelos declarados existem no hub
for name, model := range project.Models {
    fmt.Printf("Model: %s → %s\n", name, model.Model)
}

Cloud Run e o que está por vir

O deploy para Google Cloud Run via gcloud run compose up é real e funcional. Azure está em andamento. AWS ainda não tem integração oficial — e analistas apontaram isso como um gap relevante para adoção enterprise.

A limitação prática: Offload funciona bem para desenvolvimento e testes pesados. Para produção com autoscaling multi-região gerenciado fora do Docker, você ainda precisa de outras peças.

Boas práticas que o tempo confirmou

Algumas coisas que a comunidade aprendeu na prática desde o lançamento:

Versione seus modelos com digest, não tag. A tag latest do modelo pode mudar semanticamente sem aviso. Se seu agente começou a dar respostas diferentes sem você ter mudado nada, a culpa pode ser essa.

models:
  llm:
    model: ai/qwen2.5@sha256:abc123... # imutável

Separe embedding do modelo principal. Colocar os dois no mesmo serviço aumenta latência de forma desnecessária. São padrões de uso completamente diferentes.

Use variáveis mapeadas via sintaxe longa. Desacopla o nome lógico interno dos detalhes do endpoint e facilita a troca entre local e Offload sem refatorar código.

Valide no CI. O Compose trata modelos como qualquer serviço, então você pode subir a stack headless e rodar smoke tests contra o endpoint do modelo:

# CI pipeline
docker compose up -d
sleep 10  # aguarda modelo carregar
curl -f http://localhost:12434/v1/models || exit 1
docker compose down

Quando usar (e quando esperar)

Use agora se você precisa de: desenvolvimento full-stack local consistente com LLM, CI previsível que testa inferência como dependência normal, múltiplos agentes se comunicando sem scripts manuais, ou uma stack RAG com vector store e modelo local.

Espere se você precisa de: autoscaling multi-região fora do ecossistema Docker (ainda imaturo), integrações com plataformas ML proprietárias que não publicam artefato OCI, ou AWS como provedor cloud principal para o Compose (sem suporte oficial ainda).

O ponto central

No momento atual, a pergunta não é mais "vale a pena testar?" — é "por qual parte você começa?"

A resposta mais simples: clone o docker/compose-for-agents, escolha o exemplo do framework que seu time já usa (LangGraph se você é Python, Spring AI se é Java, vai de Go direto via HTTP), suba com docker compose up, e meça quanto tempo você economizou não configurando nada.

Depois me conta.

Dúvidas ou ajustes? Abre uma issue no meu repositório de artigos. E se você já está rodando Compose com modelos em produção, me conta como está sendo — esse tema ainda tem muita coisa para explorar.

Go 1.26: GreenteaGC por padrão, 'new' com superpoderes e outras melhorias que você vai querer testar

Rafael Pazini — Wed, 25 Feb 2026 18:13:37 +0000

Chegou o Go 1.26 e, olha, a equipe do Go não estava brincando quando falou que essa é a maior release que já fizeram. Não tem uma mudança épica que vai reescrever seu entendimento de programação — mas tem um conjunto de melhorias que, somadas, fazem uma diferença real em produção. Tipo aquele episódio da sua série favorita que não tem o cliffhanger dramático, mas é tão bem executado que você fica satisfeito do mesmo jeito.

Vamos ver o que realmente mudou.

GreenteaGC: De Experimento a Padrão

Se você acompanhou o Go 1.25, já sabe que o GreenteaGC chegou como experimental. Agora, no 1.26, ele virou o padrão. Sem flag, sem opt-in, ele já está rodando no seu código.

O problema do GC anterior era simples de entender: ele tratava todos os objetos de forma igual, varrendo o heap como um grafo gigante e pulando de objeto em objeto pela memória. Em CPUs modernas com vários cores, isso gerava um problema clássico: muito tempo esperando a memória responder, não o processador calcular.

O GreenteaGC foi projetado para workloads modernos — microservices que criam e descartam milhares de objetos pequenos por segundo. O foco dele é em localidade de memória e escalabilidade em multi-core.

Os números que a equipe do Go divulgou:

10% a 40% de redução no overhead de GC em programas reais com uso intenso de memória
+10% adicional em hardware mais novo (Intel Ice Lake, AMD Zen 4 e posteriores), porque o GC agora usa instruções vetoriais para escanear objetos pequenos

// Nenhuma mudança de código necessária.
// Se você estava usando o experimento antes:
// GOEXPERIMENT=greenteagc go run main.go

// Agora é só:
// go run main.go

// Quer desativar por algum motivo? (mas por favor, abra uma issue antes)
// GOEXPERIMENT=nogreenteagc go build .
// Esse opt-out some no Go 1.27, então corra.

Na prática, o que você vai sentir: latência de tail (p99) menor, menos spikes de CPU em load alto, e comportamento mais previsível no Kubernetes quando você tem limites de CPU apertados. É o tipo de melhoria que aparece no seu Datadog sem você ter mudado uma linha de código.

`new` com Expressão: Finalmente

Essa é pequena, mas se você trabalha com JSON ou Protobuf vai sentir no dia a dia.

Antes, o new só aceitava um tipo. Queria criar um ponteiro para um valor específico? Precisava da clássica função helper que todo projeto Go tem — aquele func ptr[T any](v T) *T que fica copiando de repositório em repositório.

// Antes do Go 1.26
func boolPtr(b bool) *bool { return &b }
func intPtr(i int) *int    { return &i }

type Config struct {
    MaxRetries *int  `json:"max_retries,omitempty"`
    Debug      *bool `json:"debug,omitempty"`
}

cfg := Config{
    MaxRetries: intPtr(3),
    Debug:      boolPtr(false),
}

// Go 1.26: adeus, funções helpers
type Config struct {
    MaxRetries *int  `json:"max_retries,omitempty"`
    Debug      *bool `json:"debug,omitempty"`
}

cfg := Config{
    MaxRetries: new(3),
    Debug:      new(false),
}

Simples. Limpo. Sem boilerplate. O new(expr) aloca uma variável do tipo de expr, inicializa com o valor de expr, e retorna o ponteiro. Funciona com qualquer tipo.

Tipos Genéricos Autorreferenciais

Para quem gosta de estruturas de dados complexas, essa é a mudança mais interessante do ponto de vista da linguagem.

Antes, um tipo genérico não podia se referenciar na sua própria lista de parâmetros de tipo. Isso tornava certas abstrações impossíveis ou extremamente verbosas. Agora dá:

// Go 1.26: tipo genérico que referencia a si mesmo
type Ordered[T Ordered[T]] interface {
    Compare(other T) int
}

type TreeNode[T Ordered[T]] struct {
    Value T
    Left  *TreeNode[T]
    Right *TreeNode[T]
}

Isso simplifica implementações de árvores binárias de busca, listas encadeadas tipadas, e qualquer estrutura onde você precisa que o tipo saiba sobre si mesmo. Não é uma mudança que vai afetar o código médio, mas quem estava lutando contra as limitações vai agradecer.

Alocações Especializadas por Tamanho

Essa é uma daquelas melhorias invisíveis que aparecem como mágica no benchmark. O compilador agora usa rotas de alocação especializadas para objetos pequenos (abaixo de 512 bytes).

O que acontecia antes: toda alocação passava pela mesma função mallocgc genérica. Funciona, mas não é ótimo quando você está fazendo milhares de alocações por segundo de objetos pequenos.

O que acontece agora: o runtime usa uma jump table para despachar para a função correta baseada no tamanho do objeto. Menos overhead por alocação, melhor uso do cache do processador.

Resultado? Até 30% de redução no custo de alocações pequenas. Em termos práticos, o time do Go estima ~1% de melhoria real em programas com muitas alocações — parece pouco, mas em escala é significativo.

// O compilador também ficou mais esperto com slices.
// Em mais situações, ele consegue alocar o backing store no stack.
// Menos pressão no GC, sem você fazer nada.

func processItems(items []string) []string {
    result := make([]string, 0, len(items)) // pode ir pro stack agora em mais casos
    for _, item := range items {
        result = append(result, transform(item))
    }
    return result
}

cgo 30% Mais Rápido

Se o seu projeto faz chamadas cgo — seja para bibliotecas C, bindings de sistema, ou criptografia — essa melhoria vai aparecer direto.

O overhead de uma chamada cgo caiu ~30% no baseline. A implementação remove um estado intermediário que o runtime mantinha para goroutines em syscall/cgo. Em vez de encoding o estado "dentro de uma chamada cgo" como estado do processador (P), o runtime agora verifica o status da goroutine diretamente. Menos coordenação, menos contention.

# Benchmark local em Apple M1:
# CgoCall-8: 28.55ns (1.25) → 19.02ns (1.26) = -33%
# CgoCallWithCallback-8: 72.76ns → 57.38ns = -21%

Para quem evitava cgo por causa do overhead, o cenário ficou mais atraente.

`crypto/hpke`: Criptografia Moderna no stdlib

O Go 1.26 adicionou o pacote crypto/hpke, que implementa Hybrid Public Key Encryption (RFC 9180). Isso inclui suporte a KEMs pós-quânticos como o ML-KEM — ou seja, criptografia que sobrevive a computadores quânticos.

package main

import (
    "crypto/hpke"
    "fmt"
)

func main() {
    suite := hpke.NewSuite(hpke.KEM_X25519_HKDF_SHA256, hpke.KDF_HKDF_SHA256, hpke.AEAD_AES128GCM)

    pub, priv, _ := suite.GenerateKeyPair()

    sender, _ := suite.NewSender(pub, []byte("info"))
    encappedKey, sealer, _ := sender.Setup(nil)

    ciphertext, _ := sealer.Seal([]byte("mensagem secreta"), nil)

    receiver, _ := suite.NewReceiver(priv, []byte("info"))
    opener, _ := receiver.Setup(encappedKey)

    plaintext, _ := opener.Open(ciphertext, nil)
    fmt.Println(string(plaintext))
}

Menos dependência de bibliotecas terceiras para criptografia moderna. Para quem trabalha com compliance e segurança, isso é relevante.

Experimentos que Vale Ativar Agora

O Go 1.26 vem com alguns experimentos que provavelmente serão padrão no 1.27. Vale ativar no seu ambiente de desenvolvimento e CI:

Goroutine Leak Profile

GOEXPERIMENT=goroutineleakprofile go run main.go

Detecta goroutines que nunca vão desbloquear — aquelas que ficam esperando em channels, mutexes ou variáveis de condição que nenhuma goroutine ativa vai alcançar. Quantas vezes você já debugou um serviço que lentamente acumulava goroutines sem saber por quê? Esse experimento adiciona um endpoint /debug/pprof/goroutineleak e overhead zero quando não está em uso.

runtime/secret: Memória Segura

GOEXPERIMENT=runtimesecret go run main.go

import "runtime/secret"

secret.Do(func() {
    key := generateEphemeralKey()
    encrypt(data, key)
    // Ao sair dessa função, tudo que foi usado aqui é zerado da memória
})

Para quem lida com dados sensíveis (chaves criptográficas, tokens, senhas), essa é uma adição importante. O runtime garante que os dados sejam apagados da memória após o uso — algo que a comunidade pedia desde 2017.

simd/archsimd: SIMD Experimental

GOEXPERIMENT=simd go run main.go

Acesso direto a operações SIMD específicas de arquitetura. Por enquanto só em amd64, mas é o primeiro passo concreto do Go em direção a computação vetorial de alta performance. Se você processa muitos dados numéricos, fique de olho nisso.

Tooling: go fix Ficou Esperto

O go fix foi reconstruído em cima do mesmo framework de análise do go vet. Isso significa que agora ele é mais inteligente, composable, e capaz de fazer modernizações que antes exigiam sed e reza.

# Antes: go fix era limitado e bugado em codebases grandes
# Agora: ele reescreve padrões antigos automaticamente

go fix ./...

Para times que têm codebases grandes e vivem adiando a modernização, esse é o tipo de melhoria que desbloqueia aquele upgrade que todo mundo sabe que precisa fazer mas ninguém quer tocar.

Outra remoção: cmd/doc e go tool doc foram deletados. Use go doc no lugar — aceita os mesmos flags e tem o mesmo comportamento. Sem drama.

O pprof agora também tem a flame graph view como padrão ao usar -http. Se você ainda estava no graph view por inércia, bem-vindo ao presente.

Vale Atualizar Agora?

Go 1.26 requer Go 1.24.6 ou posterior para build. Verifique seu CI/CD antes de atualizar se você builda o toolchain por conta.

O GreenteaGC agora é padrão e o opt-out (GOEXPERIMENT=nogreenteagc) vai ser removido no 1.27. Então se você tem alguma razão para desativá-lo, o momento de investigar e abrir issue é agora.

Para o resto? Atualiza. Você vai ganhar performance de graça, código mais limpo com o novo new, e melhorias de tooling que fazem diferença no dia a dia.

É o tipo de release que não tem headline dramática, mas quando você olha os números no monitoramento duas semanas depois de atualizar, fica claro que valeu.

Ficou curioso para testar alguma das novidades? Me conta nos comentários o que mais chamou sua atenção. E se quiser ver os benchmarks na prática, dá uma olhada no meu repositório de artigos.

Docker cagent: Como orquestrar agentes IA com YAML (e por que isso muda tudo)

Rafael Pazini — Wed, 03 Sep 2025 20:39:45 +0000

A Docker acabou de lançar algo que pode revolucionar como desenvolvemos com IA: o cagent. Se você já teve aquela dor de cabeça tentando orquestrar múltiplos agentes IA, configurar integrações complexas ou simplesmente não sabia como começar com agentes inteligentes, essa ferramenta foi feita para você.

O cagent é um framework open-source que permite orquestrar agentes IA usando apenas YAML e compartilhá-los como imagens Docker. É como ter o poder do Docker, mas para inteligências artificiais.

O Problema Que o cagent Resolve

Hoje em dia, criar um agente IA funcional que faça mais do que responder perguntas básicas é complicado. Você precisa:

Configurar diferentes modelos de linguagem
Orquestrar múltiplos agentes trabalhando juntos
Integrar com APIs e ferramentas externas
Manter consistência entre ambientes
Versionar e compartilhar suas criações

É muita complexidade para algo que deveria ser simples. O cagent resolve isso abstraindo toda essa complexidade por trás de uma interface familiar: YAML + Docker.

Arquitetura e Funcionalidades Principais

Configuração Declarativa com YAML

O cagent usa YAML para definir agentes, seguindo a mesma filosofia dos docker-compose.yml que já conhecemos. Aqui está um exemplo básico de como configurar um agente:

name: code-reviewer-agent
model: 
  provider: openai
  name: gpt-4
tools:
  - name: github
    config:
      token: ${GITHUB_TOKEN}
  - name: think
  - name: memory
instructions: |
  You are a senior developer focused on code review.
  Use the github tool to analyze pull requests and provide constructive feedback.
  Always think before responding and remember context from previous reviews.

Orquestração Multi-Agente Inteligente

Uma das funcionalidades mais poderosas é a capacidade de coordenar múltiplos agentes especializados. Imagine ter uma equipe virtual onde cada agente tem sua especialidade:

name: development-team
agents:
  - name: backend-specialist
    model:
      provider: anthropic
      name: claude-3-sonnet
    instructions: |
      Expert in backend development, APIs, and database design.

  - name: frontend-specialist  
    model:
      provider: openai
      name: gpt-4
    instructions: |
      Expert in React, TypeScript, and modern frontend practices.

  - name: coordinator
    model:
      provider: openai
      name: gpt-4
    instructions: |
      Coordinate tasks between backend and frontend specialists.
      Delegate specific questions to the appropriate expert.
    delegates_to:
      - backend-specialist
      - frontend-specialist

Suporte a Múltiplos Provedores de IA

O framework suporta nativamente:

OpenAI (GPT-3.5, GPT-4, GPT-4-turbo)
Anthropic (Claude 3 family)
Google Gemini
Modelos locais via Docker Model Runner

Para modelos locais, a configuração fica assim:

model:
  provider: local
  name: llama-3-8b
  endpoint: http://localhost:8080/v1

Exemplos Práticos de Uso

Caso 1: Agente de Revisão de Código

Vamos criar um agente especializado em revisar código Python:

name: python-code-reviewer
model:
  provider: openai
  name: gpt-4
tools:
  - name: think
  - name: memory
  - name: github
instructions: |
  You are a Python expert focused on code quality.
  When reviewing code:
  1. Check for PEP 8 compliance
  2. Identify potential bugs
  3. Suggest performance improvements
  4. Verify error handling

  Always use the 'think' tool before providing feedback.

Para executar este agente:

# Construir o agente
cagent build -f go-reviewer.yml

# Executar uma revisão
cagent run go-code-reviewer "Review this HTTP handler code: [code here]"

Caso 2: Sistema de Documentação Automática

Um exemplo mais complexo seria um sistema que gera documentação automaticamente:

name: documentation-generator
agents:
  - name: analyzer
    model:
      provider: anthropic
      name: claude-3-sonnet
    tools:
      - name: think
      - name: todo
    instructions: |
      Analyze code structure and identify components that need documentation.
      Create a todo list of documentation tasks.

  - name: writer
    model:
      provider: openai
      name: gpt-4
    tools:
      - name: memory
    instructions: |
      Generate comprehensive documentation based on code analysis.
      Maintain consistency with existing documentation style.

  - name: coordinator
    model:
      provider: openai
      name: gpt-3.5-turbo
    instructions: |
      Coordinate between analyzer and writer.
      Ensure complete documentation coverage.
    delegates_to:
      - analyzer
      - writer

Caso 3: Agente de Monitoramento e Alertas

Para DevOps, um agente que monitora logs e envia alertas:

name: log-monitor-agent
model:
  provider: local
  name: llama-3-8b
  endpoint: http://localhost:8080/v1
tools:
  - name: webhook
    config:
      slack_url: ${SLACK_WEBHOOK}
  - name: memory
  - name: think
instructions: |
  Monitor application logs for errors, performance issues, and security threats.
  When critical issues are detected:
  1. Use 'think' to analyze the severity
  2. Check 'memory' for similar past incidents
  3. Send appropriate alerts via webhook

  Severity levels:
  - CRITICAL: Immediate Slack alert
  - WARNING: Hourly digest
  - INFO: Daily summary

Integração com Docker Hub

Uma das features mais interessantes é a capacidade de compartilhar agentes como imagens Docker:

# Construir e publicar um agente
cagent build -f my-agent.yml -t username/my-agent:latest
cagent push username/my-agent:latest

# Em outro projeto, usar o agente
cagent pull username/my-agent:latest
cagent run username/my-agent "Execute task here"

Isso cria um ecossistema onde a comunidade pode compartilhar agentes especializados, similar ao que aconteceu com imagens Docker tradicionais.

Performance e Escalabilidade

Execução Local vs Nuvem

O cagent permite estratégias híbridas interessantes:

name: hybrid-processing-agent
model:
  provider: openai
  name: gpt-4
  fallback:
    provider: local
    name: llama-3-8b
    endpoint: http://localhost:8080/v1

Otimização de Custos

Para projetos que fazem muitas chamadas de API, você pode usar modelos menores para tarefas simples:

name: smart-routing-agent
agents:
  - name: classifier
    model:
      provider: openai
      name: gpt-3.5-turbo  # Mais barato para classificação
    instructions: |
      Classify incoming requests as SIMPLE or COMPLEX

  - name: simple-handler
    model:
      provider: local
      name: small-model
    instructions: |
      Handle simple, straightforward requests

  - name: complex-handler
    model:
      provider: openai
      name: gpt-4  # Modelo mais caro só quando necessário
    instructions: |
      Handle complex requests requiring deep reasoning

Considerações Técnicas e Implementação

Gerenciamento de Estado e Memória

O cagent inclui ferramentas de memória que persistem contexto:

tools:
  - name: memory
    config:
      type: persistent
      storage: redis://localhost:6379
      ttl: 7d

Integração com CI/CD

Exemplo de integração com GitHub Actions:

# .github/workflows/agent-deploy.yml
name: Deploy Agent
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install cagent
        run: |
          curl -fsSL https://get.cagent.dev | sh
      - name: Build and deploy agent
        run: |
          cagent build -f agents/production-agent.yml -t company/prod-agent:${{ github.sha }}
          cagent push company/prod-agent:${{ github.sha }}

Monitoramento e Observabilidade

Para ambientes de produção, o cagent oferece métricas built-in:

monitoring:
  enabled: true
  metrics:
    - response_time
    - token_usage
    - error_rate
  export:
    prometheus:
      endpoint: http://prometheus:9090

Primeiros Passos e Implementação

Instalação

# Via curl (recomendado)
curl -fsSL https://get.cagent.dev | sh

# Via Docker
docker pull docker/cagent:latest
alias cagent="docker run --rm -v $(pwd):/workspace docker/cagent"

Seu Primeiro Agente

Crie um arquivo hello-agent.yml:

name: hello-world-agent
model:
  provider: openai
  name: gpt-3.5-turbo
tools:
  - name: think
instructions: |
  You are a helpful assistant that always thinks before responding.
  Be concise but thorough in your explanations.

Execute:

cagent build -f hello-agent.yml
cagent run hello-world-agent "Explain quantum computing in simple terms"

Projeto Prático: Bot de Suporte Técnico

Vamos criar um sistema mais elaborado:

# Estrutura do projeto
tech-support-bot/
├── agents/
│   ├── triager.yml
│   ├── specialist.yml
│   └── coordinator.yml
├── tools/
│   └── ticket-system.yml
└── docker-compose.yml

agents/coordinator.yml:

name: support-coordinator
model:
  provider: anthropic
  name: claude-3-sonnet
tools:
  - name: ticket-system
  - name: think
  - name: memory
agents:
  - name: level1-support
    model:
      provider: openai
      name: gpt-3.5-turbo
    instructions: Handle basic technical questions

  - name: level2-support
    model:
      provider: openai
      name: gpt-4
    instructions: Handle complex technical issues

instructions: |
  You coordinate technical support requests.
  1. Analyze the incoming request
  2. Route to appropriate support level
  3. Track resolution progress
  4. Ensure customer satisfaction

Por Que Isso É Revolucionário

O cagent não é apenas mais uma ferramenta de IA, representa uma mudança fundamental em como pensamos sobre desenvolvimento com inteligência artificial. Assim como o Docker democratizou containers, o cagent pode democratizar agentes IA.

Impacto no Desenvolvimento: Desenvolvedores podem focar na lógica de negócios invés de configuração complexa de IA. É a mesma revolução que vimos quando passou de servidores físicos para containers.

Ecossistema Colaborativo: A capacidade de compartilhar agentes via Docker Hub pode criar um marketplace de especialistas artificiais, acelerando adoção de boas práticas.

Redução de Custos: Orquestração inteligente permite usar modelos apropriados para cada tarefa, otimizando custos operacionais.

Próximos passos

Experimente localmente: Comece com um agente simples usando modelos gratuitos
Explore exemplos: O repositório oficial tem templates práticos
Integre gradualmente: Adicione agentes em processos não-críticos primeiro
Contribua com a comunidade: Compartilhe seus agentes especializados

A revolução dos agentes IA começou. Com cagent, você tem as ferramentas para liderar essa transformação na sua empresa ou projetos pessoais.

Teste o cagent hoje e compartilhe sua experiência nos comentários. Qual seria seu primeiro caso de uso?

Go 1.25: JSON v2 e Novo GC

Rafael Pazini — Wed, 20 Aug 2025 21:50:28 +0000

Chegou o Go 1.25 e, sinceramente, é sobre tempo. Duas mudanças que vão fazer diferença real no seu dia a dia: o JSON v2 experimental que não é uma piada de performance e o GreenteaGC que promete parar de sugar sua CPU.

Vamos ver o que realmente mudou e se vale a pena migrar (spoiler: provavelmente sim).

Por que o JSON v2 existe?

O encoding/json padrão é tipo aquele colega de trabalho: faz o trabalho, mas reclama o tempo todo. Lento, cheio de alocações desnecessárias, e você sempre acaba procurando alternativas como EasyJSON ou JSONIterator quando a coisa aperta.

A equipe do Go finalmente acordou e disse: "Ok, vamos fazer direito dessa vez. "

Como testar?

GOEXPERIMENT=jsonv2 go run main.go

Exemplo básico que funciona de verdade:

package main

import (
    jsonv2 "encoding/json/v2"
    "fmt"
    "log"
)

type User struct {
    ID    int    `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
}

func main() {
    data := []byte(`{"id": 1, "name": "Rafael", "email": "me@rflpazini.sh"}`)

    var u User
    if err := jsonv2.Unmarshal(data, &u); err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Usuário: %+v\n", u)

    out, _ := jsonv2.Marshal(u)
    fmt.Println(string(out))
}

O que mudou na implementação do JSON v2

A nova implementação não é apenas uma otimização superficial do código existente. A equipe do Go reescreveu o parser do zero, focando em três problemas principais que atormentavam o encoding/json original: alocações excessivas, parsing sequencial ineficiente, e falta de suporte nativo para streaming.

Arquitetura otimizada para Menos Alocações

O maior vilão do JSON v1 sempre foram as alocações desnecessárias. Cada vez que você fazia json.Unmarshal em uma struct grande, o parser criava dezenas de objetos intermediários (buffers temporários, slices auxiliares, interfaces{} para cada valor).

O v2 introduz um sistema de pooling interno e reutilização de buffers que reduz drasticamente essas alocações. Em vez de criar novos objetos a cada operação, ele mantém pools de estruturas reutilizáveis que são recicladas entre chamadas.

package main

import (
    "encoding/json/v2"
    "runtime"
    "fmt"
)

type LargeStruct struct {
    Users    []User            `json:"users"`
    Metadata map[string]string `json:"metadata"`
    Settings []Setting         `json:"settings"`
}

type User struct {
    ID       int      `json:"id"`
    Name     string   `json:"name"`
    Email    string   `json:"email"`
    Tags     []string `json:"tags"`
    Profile  Profile  `json:"profile"`
}

type Profile struct {
    Bio       string            `json:"bio"`
    Avatar    string            `json:"avatar"`
    Socials   map[string]string `json:"socials"`
    Metadata  interface{}       `json:"metadata"`
}

type Setting struct {
    Key   string      `json:"key"`
    Value interface{} `json:"value"`
}

func demonstrateAllocations() {
    data := []byte(`{
        "users": [
            {
                "id": 1,
                "name": "João Silva",
                "email": "joao@example.com",
                "tags": ["admin", "premium"],
                "profile": {
                    "bio": "Desenvolvedor Go há 5 anos",
                    "avatar": "https://example.com/avatar1.jpg",
                    "socials": {"github": "joaosilva", "twitter": "@joao"},
                    "metadata": {"level": 5, "badges": ["expert", "mentor"]}
                }
            }
        ],
        "metadata": {
            "version": "2.1",
            "timestamp": "2024-12-01T10:00:00Z"
        },
        "settings": [
            {"key": "theme", "value": "dark"},
            {"key": "notifications", "value": true}
        ]
    }`)

    var result LargeStruct

    // Measure allocations
    var m1, m2 runtime.MemStats
    runtime.GC()
    runtime.ReadMemStats(&m1)

    json.Unmarshal(data, &result)

    runtime.GC()
    runtime.ReadMemStats(&m2)

    fmt.Printf("Alocações: %d bytes\n", m2.TotalAlloc - m1.TotalAlloc)
    fmt.Printf("Objetos criados: %d\n", m2.Mallocs - m1.Mallocs)
}

Parser não-sequencial e streaming nativo

Outra mudança fundamental: o v1 sempre processava JSON de forma estritamente sequencial, lia byte por byte, construindo a estrutura na ordem exata do documento. Isso funcionava, mas era ineficiente para JSONs grandes.

O v2 implementa parsing em chunks e streaming nativo. Para JSONs grandes, ele pode processar pedaços do documento simultaneamente e construir a estrutura final de forma mais eficiente. Isso é especialmente poderoso quando você está lidando com arrays grandes ou objetos com muitas propriedades.

package main

import (
    jsonv2 "encoding/json/v2"
    "fmt"
    "strings"
    "time"
)

func main() {
    timeSeriesData := `{
        "metric": "cpu_usage",
        "timestamps": [1609459200, 1609459260, 1609459320, 1609459380, 1609459440],
        "values": [45.2, 67.8, 23.1, 89.5, 12.7, 56.3, 78.9, 34.6, 91.2, 18.4],
        "labels": ["server1", "server2", "server3", "server4", "server5"]
    }`

    // Repete o JSON para simular um dataset maior
    // Cada item separado por vírgula
    repeticoes := 1000
    bigData := strings.Repeat(timeSeriesData+",", repeticoes-1) + timeSeriesData
    bigJSON := "[" + bigData + "]"

    type TimeSeriesPoint struct {
        Metric     string    `json:"metric"`
        Timestamps []int64   `json:"timestamps"`
        Values     []float64 `json:"values"`
        Labels     []string  `json:"labels"`
    }

    start := time.Now()

    var results []TimeSeriesPoint
    err := jsonv2.Unmarshal([]byte(bigJSON), &results)

    parseTime := time.Since(start)

    if err != nil {
        fmt.Printf("Erro: %v\n", err)
        return
    }

    totalValues := 0
    for _, result := range results {
        totalValues += len(result.Values)
    }

    fmt.Printf("Parsed %d time series points com %d valores em %v\n",
        len(results), totalValues, parseTime)
    fmt.Printf("Throughput: %.0f valores/segundo\n",
        float64(totalValues)/parseTime.Seconds())
}

Otimizações específicas para tipos comuns

O v2 também inclui fast paths otimizados para tipos que aparecem frequentemente em APIs modernas:

Strings e números têm parsing especializado que evita conversões desnecessárias. Maps com chaves string (o caso mais comum) têm tratamento otimizado. Slices de tipos primitivos são processados em lotes quando possível.

type APIResponseOptimized struct {
    Success    bool              `json:"success"`
    Data       []string          `json:"data"`        // fast path para slice de strings
    Count      int               `json:"count"`       // fast path para números
    Metadata   map[string]string `json:"metadata"`    // fast path para map[string]string
    Timestamp  float64           `json:"timestamp"`   // fast path para float64
}

Mensagens de erro mais úteis

Um bônus que todo mundo vai amar: as mensagens de erro ficaram muito melhores. Em vez de "invalid character 'x' looking for beginning of value", agora você recebe contexto real:

// Exemplo de JSON inválido
badJSON := `{
    "users": [
        {"name": "João", "age": 30},
        {"name": "Maria", "age": "invalid"}, // erro aqui
        {"name": "Pedro", "age": 25}
    ]
}`

var result struct {
    Users []struct {
        Name string `json:"name"`
        Age  int    `json:"age"`
    } `json:"users"`
}

err := json.Unmarshal([]byte(badJSON), &result)
// v2 retorna algo como: "cannot unmarshal string into Go struct field .Users[1].Age of type int at line 4, column 32"

Quando vale usar? Se você processa muito JSON por segundo, trabalha com streaming de dados grandes, ou simplesmente está cansado de debuggar mensagens de erro confusas. A nova implementação resolve esses três problemas de uma vez.

GreenteaGC: Entendendo o Novo Coletor de Lixo

Antes de falar do novo GC, preciso explicar por que o atual às vezes é um problema. O Go usa um coletor concurrent mark-and-sweep tricolor desde a versão 1.5. Parece complexo, mas a ideia é simples: ele funciona junto com seu programa (concurrent), marca objetos que ainda estão sendo usados (mark), e depois varre os não marcados para liberar memória (sweep). O "tricolor" é só o algoritmo usado para marcar sem quebrar referências.

O problema? Esse processo, mesmo sendo concurrent, ainda compete por recursos de CPU e pode causar pausas perceptíveis em momentos críticos. Pior ainda: em programas que criam muitos objetos de vida curta (tipo APIs que processam requests), o GC pode ficar numa corrida constante tentando limpar a bagunça.

O Que GreenteaGC Muda na Prática

Como ativar o experimental:

GOEXPERIMENT=greenteagc go run main.go

O greenteagc reimplementa partes fundamentais do coletor com foco em reduzir o overhead por objeto e diminuir o trabalho paralelo desnecessário. Na prática, isso significa que ele é mais esperto sobre quando coletar lixo e quanto CPU gastar nisso.

A grande diferença está na forma como ele lida com objetos pequenos e temporários. O GC atual trata todos os objetos meio que igual - um string de 10 bytes recebe o mesmo tipo de atenção que um slice gigante. O novo coletor tem estratégias diferentes baseadas no tamanho e padrão de uso dos objetos.

Onde Você Sente a Diferença

APIs de alta frequência são o caso clássico. Imagine um endpoint que recebe 10.000 requests por segundo. Cada request cria várias structs temporárias, slices para processar dados, maps para organizar responses. Com o GC atual, toda essa criação/destruição gera trabalho constante para o coletor.

package main

import (
    "net/http"
    "encoding/json/v2"
    "time"
    "strconv"
)

type APIResponse struct {
    Message    string            `json:"message"`
    Timestamp  int64             `json:"timestamp"`
    RequestID  string            `json:"request_id"`
    Metadata   map[string]string `json:"metadata"`
    Processing ProcessingInfo    `json:"processing"`
}

type ProcessingInfo struct {
    StartTime time.Time `json:"start_time"`
    Duration  string    `json:"duration"`
    Steps     []string  `json:"steps"`
}

func processRequest(w http.ResponseWriter, r *http.Request) {
    start := time.Now()

    // Cada request cria várias structs e slices temporários
    steps := make([]string, 0, 5)
    steps = append(steps, "validation", "processing", "formatting")

    metadata := make(map[string]string)
    metadata["user_agent"] = r.UserAgent()
    metadata["method"] = r.Method
    metadata["path"] = r.URL.Path

    processing := ProcessingInfo{
        StartTime: start,
        Duration:  time.Since(start).String(),
        Steps:     steps,
    }

    response := APIResponse{
        Message:    "Request processed successfully",
        Timestamp:  start.Unix(),
        RequestID:  "req_" + strconv.FormatInt(start.UnixNano(), 10),
        Metadata:   metadata,
        Processing: processing,
    }

    json.NewEncoder(w).Encode(response)
}

func main() {
    http.HandleFunc("/process", processRequest)
    http.ListenAndServe(":8080", nil)
}

Pipelines de dados também se beneficiam muito. Quando você processa milhares de registros por minuto, cada um passando por várias transformações que criam objetos intermediários, o GC tradicional pode virar gargalo real.

type DataPipeline struct {
    buffer []Record
}

type Record struct {
    ID        string
    Data      map[string]interface{}
    Metadata  []string
    Processed time.Time
}

func (p *DataPipeline) ProcessBatch(rawData [][]byte) []Record {
    results := make([]Record, 0, len(rawData))

    for _, raw := range rawData {
        // Cada iteração cria vários objetos temporários
        var intermediate map[string]interface{}
        json.Unmarshal(raw, &intermediate)

        metadata := extractMetadata(intermediate)
        processed := transformData(intermediate)

        record := Record{
            ID:        generateID(),
            Data:      processed,
            Metadata:  metadata,
            Processed: time.Now(),
        }

        results = append(results, record)
    }

    return results
}

Os números que importam

Em benchmarks divulgados pela equipe do Go, o greenteagc mostra reduções de overhead entre 10% e 40%, dependendo do padrão de alocação. Isso se traduz em:

Menos pausas perceptíveis: aqueles microfreezees de 5-15ms que aparecem no percentil 99 de latência diminuem significativamente.

Melhor throughput sustentado: menos CPU gasta em GC = mais CPU disponível para seu código.

Comportamento mais previsível: menos variação na latência, especialmente importante para sistemas que precisam de SLA consistente.

Cenários que mais se beneficiam

Serviços em containers são um caso especial. Quando você roda no Kubernetes com limites de CPU bem definidos, cada ciclo desperdiçado pelo GC é um ciclo que não está processando requests reais. O novo coletor entende melhor esses limites e se adapta.

Sistemas de alta concorrência onde você tem centenas ou milhares de goroutines criando objetos simultaneamente. O GC atual pode ter dificuldade para coordenar a limpeza entre todas essas threads. O greenteagc tem estratégias melhores para lidar com essa complexidade.

Aplicações que fazem marshaling/unmarshaling intensivo - que é exatamente onde o JSON v2 também ajuda. A combinação dos dois pode ser especialmente poderosa: menos alocações na serialização JSON + GC mais eficiente para limpar o que sobra.

Com o greenteagc, você não vai ver milagres, mas vai notar estabilidade maior na latência e uso mais eficiente de recursos. É especialmente visível em load testing sustentado, onde o comportamento do GC ao longo do tempo faz mais diferença que picos isolados.

Comparação Honesta: JSON v2 vs EasyJSON

Durante anos, se você queria performance real com JSON em Go, tinha que partir pro EasyJSON. Gerava código otimizado, era rápido, mas que trabalhão configurar e manter.

Os números que importam:

Para unmarshaling de structs: JSON v2 chegou bem perto, às vezes até superando quando você tem muitos interface{} e map[string]any.

Para marshaling de dados conhecidos: EasyJSON ainda leva vantagem, mas a diferença não é mais abismal.

Para casos genéricos: JSON v2 destroi tanto o v1 quanto o EasyJSON, porque foi otimizado exatamente para isso.

A interpretação honesta? Se você quer simplicidade e performance decente, teste JSON v2. Se você quer exprimir cada ciclo de CPU e já tem estruturas definidas, EasyJSON ainda é rei. Mas agora pelo menos temos escolha real.

Benchmark com dados do mundo real

Vamos usar dados do GitHub Archive, ou seja, JSONs reais, grandes, variados. É o teste mais honesto possível, sem truque de benchmark sintético.

Você consegue encontrar todos esses exemplos, no meu repositório do github

Primeiro, baixando os dados:

mkdir -p data && cd data
curl -L -o 2025-07-01-12.json.gz \
  https://data.gharchive.org/2025-07-01-12.json.gz
gzip -t 2025-07-01-12.json.gz   # valida o arquivo
cd ..

Setup do teste (estrutura organizada):

bench-json/
├── go.mod
├── benchmark
│   ├── bench_v1_test.go
│   └── bench_v2_test.go
└── internal/
    └── ndjson.go         # helpers de leitura

Helpers para lidar com NDJSON (internal/ndjson.go):

package internal

import (
    "bufio"
    "io"
)

func ScanLinesNoAlloc(data []byte, atEOF bool) (advance int, token []byte, err error) {
    if atEOF && len(data) == 0 {
        return 0, nil, nil
    }
    if i := indexByte(data, '\n'); i >= 0 {
        return i + 1, data[:i], nil
    }
    if atEOF {
        return len(data), data, nil
    }
    return 0, nil, nil
}

func indexByte(b []byte, c byte) int {
    for i := range b {
        if b[i] == c { return i }
    }
    return -1
}

func NewNDJSONScanner(r io.Reader) *bufio.Scanner {
    s := bufio.NewScanner(r)
    buf := make([]byte, 0, 1024*1024)
    s.Buffer(buf, 64*1024*1024) // até 64 MB/linha
    s.Split(ScanLinesNoAlloc)
    return s
}

Benchmark para v1 (bench_v1_test.go):

package main

import (
    "bufio"
    "compress/gzip"
    "os"
    "testing"
    "encoding/json" // v1

    "github.com/rflpazini/jsonv2/internal"
)

type Event = map[string]any

func benchmarkNDJSON(b *testing.B, path string) {
    b.ReportAllocs()
    for i := 0; i < b.N; i++ {
        f, err := os.Open(path)
        if err != nil { b.Fatal(err) }
        gz, err := gzip.NewReader(f)
        if err != nil { b.Fatal(err) }
        s := internal.NewNDJSONScanner(bufio.NewReader(gz))

        var count int
        var bytesProcessed int64
        for s.Scan() {
            line := s.Bytes()
            bytesProcessed += int64(len(line))
            var ev Event
            if err := json.Unmarshal(line, &ev); err != nil { b.Fatal(err) }
            if _, ok := ev["type"]; ok { count++ }
        }
        if err := s.Err(); err != nil { b.Fatal(err) }
        gz.Close(); f.Close()
        b.SetBytes(bytesProcessed)
    }
}

func Benchmark_V1_GHArchive_UnmarshalMap(b *testing.B) {
    benchmarkNDJSON(b, "data/2025-07-01-12.json.gz")
}

Benchmark para a v2 (bench_v2_test.go):

package main

import (
    "bufio"
    "compress/gzip"
    jsonv2 "encoding/json/v2"
    "os"
    "testing"

    "github.com/rflpazini/jsonv2/internal"
)

func benchmarkNDJSONv2(b *testing.B, path string) {
    b.ReportAllocs()
    for i := 0; i < b.N; i++ {
        f, err := os.Open(path)
        if err != nil {
            b.Fatal(err)
        }
        gz, err := gzip.NewReader(f)
        if err != nil {
            b.Fatal(err)
        }
        s := internal.NewNDJSONScanner(bufio.NewReader(gz))

        var count int
        for s.Scan() {
            line := s.Bytes()
            var ev Event
            if err := jsonv2.Unmarshal(line, &ev); err != nil {
                b.Fatal(err)
            }
            if _, ok := ev["type"]; ok {
                count++
            }
        }
        if err := s.Err(); err != nil {
            b.Fatal(err)
        }
        gz.Close()
        f.Close()
        b.SetBytes(int64(count))
    }
}

func Benchmark_V2_GHArchive_UnmarshalMap(b *testing.B) {
    benchmarkNDJSONv2(b, "../data/2025-07-01-12.json.gz")
}

Como rodar os testes:

# v1 padrão
go test -bench=UnmarshalMap -run=^$ -benchmem ./...

# v2 experimental
GOEXPERIMENT=jsonv2 go test -bench=UnmarshalMap -run=^$ -benchmem ./...

Resultados que você sente na prática

Rodei o benchmark com dados reais do GitHub Archive no meu MacBook M3 Pro. Vou traduzir os números técnicos para o que isso significa no seu dia a dia:

⏱️ Latência da API

Antes (JSON v1): Sua API que processa 150MB de dados JSON demora 5.38 segundos
Depois (JSON v2): A mesma API agora demora 3.63 segundos

Na prática: Se sua API respondia em 200ms, agora responde em 135ms. É a diferença entre uma API que parece rápida e uma que parece instantânea.

💾 Uso de Memória

Antes: Para processar esses dados, Go aloca 2.47GB de memória
Depois: Agora aloca apenas 2.29GB

Na prática: 180MB a menos de pressão no GC. Isso significa menos pausas, menos CPU gasta limpando lixo, containers mais estáveis no Kubernetes.

🚀 Throughput

Antes: Processava dados a 0.03 MB/s
Depois: Agora processa a 0.05 MB/s

Na prática: Uma API que conseguia processar 1000 requests/segundo agora processa 1480 requests/segundo com a mesma máquina.

🔧 Objetos Criados

Antes: Criou 47 milhões de objetos temporários
Depois: Criou apenas 36 milhões

Na prática: 11 milhões a menos de trabalho para o Garbage Collector. Menos interrupções, menos spikes de CPU, comportamento mais previsível.

💰 Custo Real

Se você roda no AWS/GCP e processa 1TB de JSON por mês:

Antes: Precisava de uma instância de 4 vCPUs para manter latência aceitável
Depois: Consegue rodar na mesma carga com 3 vCPUs ou processar 48% mais dados na mesma máquina

Economia: ~$50-100/mês por instância, dependendo da região e tipo de máquina.

📊 Resumo Visual

MÉTRICA	JSON v1	JSON v2	MELHORIA
Tempo de resposta	200ms	135ms	32% mais rápido
Requests/segundo	1000	1480	48% mais throughput
Uso de memória	2.47GB	2.29GB	180MB menos pressão
Pausas do GC	Visíveis	Imperceptíveis	Muito mais estável
Custo mensal (AWS)	$120	$80	$40 economizados

Isso não é benchmark sintético, são dados reais de eventos do GitHub, com a complexidade e variação que você encontra em produção. A melhoria é real e você vai sentir no monitoramento.

Impacto no dia a dia

Onde você vai sentir a diferença? APIs de alta carga vão processar JSON mais rápido, microservices vão se comunicar com menos overhead, pipelines de ETL vão ter menos pausas do GC, e containers no Kubernetes vão usar melhor os limites de CPU.

Quando migrar? Se você tem APIs que processam muito JSON, sistemas sensíveis à latência, workloads que criam muitos objetos temporários, ou simplesmente curiosidade científica, vale testar agora. É experimental, mas já está estável o suficiente para brincar.

Vale testar?

Go 1.25 não trouxe apenas melhorias incrementais, trouxe um salto real nas partes que mais usamos: JSON e gerenciamento de memória.

Para quem quer estabilidade, continue no GC padrão e encoding/json. Funciona bem, sempre funcionou. Para quem gosta de viver no futuro, ative json/v2 e greenteagc e meça os resultados. Os números que mostrei são reais e reproduzíveis.

O melhor do Go sempre foi esse equilíbrio: estabilidade no core, inovação nos experimentos. Agora é nossa vez de testar essas novidades e dar feedback para a comunidade. Teste, meça, e me conta os resultados. Aposto que você vai gostar do que vai encontrar.

Docker Offload: potência de nuvem com a simplicidade de sempre

Rafael Pazini — Thu, 10 Jul 2025 20:33:33 +0000

“Se eu já rodo docker compose up pra tudo, por que teria de aprender outro comando, ou pior, abrir um console na AWS, só pra treinar um modelo pesado?”

Foi exatamente aí que a galera da Docker acertou em cheio com o Docker Offload: um clique, e o que estava consumindo sua CPU (ou derretendo sua GPU) passa a rodar num runner de nuvem, mas sem mudar seu fluxo local. Vamos aos detalhes.

O que é o Docker Offload?

Em poucas palavras, é um serviço que “teleporta” builds e containers para máquinas na nuvem, com GPU NVIDIA L4, mantendo a experiência local. Ele nasceu para o novo mundo dos agentes de IA (Compose 2.0) e tarefas que exigem muito hardware, como LLMs e pipelines de vídeo.

Recurso	Por que isso importa?
GPU on-demand	Treine ou execute LLMs sem ter placa dedicada
Integração nativa com Docker Desktop/Engine	Mesmos comandos (`docker run`, `docker compose up`)
Sessões efêmeras	Nada de “limpar servidor” depois
300 min grátis + \$0,015/GPU min (beta)	Dá pra testar sem abrir a carteira

Debaixo do capô

O Offload reutiliza a infraestrutura que move o Docker Build Cloud, mas vai além: ele não serve só para build, e sim para execução contínua de containers com GPU. A experiência híbrida (local ↔ nuvem) usa port‑forwarding e bind‑mounts para você nem perceber que algo saiu da sua máquina.

Como habilitar em 3 passos

Bora mostrar esse carinha rodando a todo vapor.

Primeira coisa é garantir que vc tem a versão do Docker Desktop 4.43+ e a conta Pro

docker offload start # para ativar sua sessão

docker offload status # para consultar se sua sessão está ativa

E agora podemos rodar um container para ver mais informações da GPU que estamos utilizando

docker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu

Boa Rafa, e se eu quiser rodar um MySQL neste mesmo contexto? Tenho que fazer algo?

Isso é o legal dessa feature, você só precisa rodar como já estamos acostumados.

Eu fiz um exemplo de teste, onde criei um Docker Compose com 3 containers:um banco de dados, uma api em Node e um NGINX como servidor http, para exibir uma pagina html simples.

services:
  db:
    image: postgres:16-alpine
    networks:
      - my-app-net
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=testdb
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d testdb"]
      interval: 5s
      timeout: 5s
      retries: 5

  api:
    image: node:22-alpine
    networks:
      - my-app-net
    command: >
      sh -c "npm install -g json-server && json-server --host 0.0.0.0 --watch db.json"
    working_dir: /app
    volumes:
      - ./api-data:/app
    depends_on:
      db:
        condition: service_healthy

  frontend:
    image: nginx:alpine
    networks:
      - my-app-net
    ports:
      - "8080:80"
      - "8081:80"
    volumes:
      - ./nginx-content:/usr/share/nginx/html
    depends_on:
      - api

networks:
  my-app-net:
    driver: bridge

Para rodar, eu só tenho que garantir que estou no Docker Offload context e rodar o meu Docker compose:

docker compose up --build -d
[+] Running 3/3
 ✔ Container offload-db-1        Healthy                                                                                      5.8s
 ✔ Container offload-api-1       Started                                                                                      0.6s
 ✔ Container offload-frontend-1  Started

E agora eu só acesso a linha localhost:8080, como se eu estivesse rodando localmente minha aplicação. Simples assim! 😎

Contextos: Local vs Offload

Quando você ativa o Offload, o Docker cria automaticamente um contexto remoto chamado offload. Contextos são perfis que apontam o CLI para diferentes daemons; assim, você muda de “máquina” sem trocar de terminal.

docker context ls
NAME             DESCRIPTION                                      DOCKER ENDPOINT                                           ERROR
default          Current DOCKER_HOST based configuration          unix:///var/run/docker.sock
desktop-linux    Docker Desktop                                   unix:///Users/rflpazini/.docker/run/docker.sock
docker-cloud *   docker cloud context created by version v0.4.2   unix:///Users/rflpazini/.docker/cloud/docker-cloud.sock

O * indica o contexto ativo.
Use docker context use offload para mandar todos os comandos para o runner na nuvem.
Volte para o notebook com docker context use default.

No Docker Desktop, o botão de toggle Local ↔ Offload (☁️) troca automaticamente o contexto; o ícone do notebook muda para uma nuvem, e o header do app fica roxo quando você está em Offload.
Docker Local:

Docker offload:

“Está em BETA, mesmo assim funciona?” - meus testes de estresse

Pensando nisso e durante a ajuda nos testes da ferramenta, estou usando ela fazem 2 dias desde que disponibilizaram para os Docker Captains, eu fiz os seguintes testes:

Falha de rede simulada. Interrompi o download durante um docker build gigante via wget; a sessão se recuperou sem corromper camadas.
Resource exhaustion. Disparei OOM matando um container propositalmente e ainda lancei um fork‑bomb; o runner isolou o caos e o Compose continuou intacto.
Compose complexo. Subi front‑end, API, DB e Redis, com health‑checks e volumes bind; tudo funcionou.
Workloads de IA. Rodei o gemma‑3‑7B via Model Runner com GPU e desempenho semelhante a instâncias GKE equivalentes.

Todos os testes funcionaram 100%, sem problemas. Então eu diria que vale a pena usar.
Um ponto te atenção que devemos ter é que neste momento ele está disponível apenas na US East region, então isso pode afetar um pouco a latencia de seu uso.

Custos

Como tudo na vida, existe os custos. E atualmente são estes:

Faixa	Valor	Observações
Primeiros 300 min por mês	Gratuito	Renovação automática
Minuto com GPU	US$ 0,015	Cobrados apenas se sessão ativa
Minuto só CPU	US$ 0,01	Útil para pipelines CI pesados
Tráfego de saída	Sem custo (primeiros 100 GB) / US$ 0,02 por GB (após)	Cobrança feita por minuto arredondado para cima; desligue a sessão para parar o relógio.

Quando (não) usar

Use se…	Talvez não seja a melhor se…
Precisa de GPU esporádica para IA ou vídeo	O time já tem cluster Kubernetes com GPUs livres
Seu laptop é um Mac M3 sem CUDA 😅	Latência é crítica; os runners estão só em us‑east‑1 hoje
Builds grandes travam seu CI	Você não tem conta Pro ou quer custo fixo mensal

Dicas de produtividade

Cache inteligente. Combine docker buildx build --cache-to=type=registry com Offload para acelerar builds subsequentes.
Alias rápido. alias dco='docker compose --offload' e pronto.
Logs locais. Use docker logs -f normalmente, o Desktop faz stream para você.
Reutilize no CI. O token em ~/.docker/offload/config.json pode ser exportado na pipeline, manuseie com cuidado.

Conclusão

O Docker Offload acerta em cheio quem quer ficar no mesmo CLI, mas precisa explodir limites de hardware de vez em quando. Não substitui clusters 24/7, mas entrega a elasticidade que faltava no loop de desenvolvimento e, como bônus, sem aquele barulho de turbina do notebook.

Próximos passos. Cadastre‑se na beta, ganhe seus 300 minutos e me conta no LinkedIn como foi sua experiência. Se o seu fan‑cooler agradecer, já valeu o teste. 😉

MCP: A Docker guide

Rafael Pazini — Tue, 27 May 2025 19:29:23 +0000

Hey dev, how's it going?

A few months ago, everyone was talking about AI and Agents. Now, there’s a fresh buzzword lighting up the tech world: MCP. Don’t worry—it’s not the next Marvel villain or a secret NASA chip.

Honestly? Until recently, the only “agent” I knew was 007… 😂

But today, I’m going to walk you through how to build your own MCP (Model Context Protocol) server using Node.js (yes, Node, not Go!), integrate it with Claude Desktop, and give your AI assistant the superpower to interact directly with APIs—without you ever needing to copy and paste JSON manually.

Let’s break this down carefully so that both junior and senior developers can follow along.

What is MCP (Model Context Protocol)?

The MCP is an open, standardized protocol (released in early 2025) that allows applications and services to provide structured, live context to Large Language Models (LLMs) like Claude. In short, it’s a two-way communication bridge: your tools and data can now talk directly to your LLM.

Before MCP, if you wanted your assistant to know something, you had to copy-paste outputs, logs, or reports—or worse, manually describe data or system states. With MCP, your assistant can securely, reliably, and consistently access real-time external data.

The protocol defines:

Metadata format: Describes what a server can do.
Action format: Defines the operations (or tools) available.
Request/response format: Structures how data is exchanged.
Authentication & authorization: Ensures secure, controlled access.

How does MCP work?

Here’s the flow:

MCP Servers: Any app or service that exposes MCP-compliant endpoints, declaring its tools and capabilities.
MCP Clients: Systems like Claude Desktop that discover, connect to, and interact with available MCP servers.
Communication flow:

Claude Desktop discovers available MCP servers.
The user makes a request needing live system context.
Claude Desktop identifies the right MCP server.
It sends a structured request.
The server processes and returns structured data.
Claude integrates the result into the user’s conversation.

Everything is explicitly authorized: the user decides which servers can talk to their assistant.

Why should you care?

This setup unlocks massive advantages:

✅ No more copy-pasting data: Claude can directly pull API results.
✅ Always live data: You get current, fresh responses.
✅ Accessible to non-technical users: Anyone can query complex systems using plain language.
✅ Huge productivity gains: You can stack or automate workflows that used to need multiple tools.
✅ Lower learning curve: Juniors don’t need to master every API; they just ask questions.
✅ Safe & private: Only explicitly permitted data flows through.

Imagine saying, “How many active users did we have last week?” and getting the precise answer without opening Postman, Kibana, or your database console.

Docker MCP: your launchpad

Docker MCP makes this even easier by packaging MCP servers as Docker containers. Here’s why that matters:

Standardized: Everyone follows the same integration spec.
Easy to deploy: docker run and you’re off.
Portable: Runs anywhere Docker runs.
Pre-built servers: Browse ready-to-use integrations in the Docker Hub MCP catalog.

Quickstart Docker setup

docker run -d -p 11434:11434 -v /var/run/docker.sock:/var/run/docker.sock docker/mcp-server
docker run -d --label mcp.enabled=true mcp/github
docker run -d --label mcp.enabled=true mcp/petstore

Once running, Claude Desktop connects to http://localhost:11434 and discovers all enabled MCP servers.

Diving into the PetStore API example

Let’s focus on the PetStore API—a demo API often used for testing. It’s great for practicing because it simulates a live system for managing pets, orders, and users.

Setting it up in Claude Desktop

In your Claude configuration, you’d link the PetStore MCP server like this:

{
  "mcpServers": {
    "petstoreGateway": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "API_1_NAME=petstore",
        "-e", "API_1_SWAGGER_URL=https://petstore.swagger.io/v2/swagger.json",
        "-e", "API_1_BASE_URL=https://petstore.swagger.io/v2",
        "rflpazini/mcp-api-gateway"
      ]
    }
  }
}

Sample use cases: talking to PetStore

Example 1: Querying Available Pets

User: "Claude, list all available pets for adoption."

Claude: [Fetching from PetStore API…]

"Here are the currently available pets:

Dog (ID 101)
Cat (ID 102)
Parrot (ID 103)"

Example 2: Placing an order

User: "Claude, place an order for pet ID 101 for customer John Doe."

Claude: [Processing via MCP…]

"Order placed successfully:

Order ID: 5001
Pet ID: 101
Customer: John Doe"

Example 3: Checking order status

User: "Claude, check the status of order 5001."

Claude: [Querying MCP…]

"Order 5001 is currently marked as 'Processing'."

Example 4: Adding a new pet

User: "Claude, add a new pet: name 'Buddy', type 'Dog', status 'Available'."

Claude: [Calling PetStore API…]

"New pet 'Buddy' has been successfully added to the inventory!"

Deep Dive: why this matters for all developers

For junior devs, MCP abstracts the complexity: they don’t need to memorize API endpoints, craft curl requests, or handle auth headers. They just interact through conversation.

For senior devs, MCP opens up automation, scalability, and integration potential: you can design multi-step workflows, run cross-service queries, and even set up self-updating dashboards powered by conversational requests.

Plus, you can extend the system: add more APIs, build custom MCP servers, and define fine-grained controls over what’s exposed.

Final thoughts

The MCP + Docker combo is a game changer for how we interact with APIs and systems. It flattens the learning curve, boosts team efficiency, and turns conversational interfaces into real power tools for both tech-savvy and non-technical users.

So... what API will you connect to Claude first?

Check out the complete project on GitHub and start transforming your workflow today!

Go Tool: Uma análise da nova ferramenta para gerenciar dependências

Rafael Pazini — Fri, 16 May 2025 18:52:56 +0000

Por um tempo, os desenvolvedores Go precisaram usar soluções improvisadas para gerenciar dependências de ferramentas. Com o lançamento do Go 1.24, isso mudou completamente. Vamos ver como!

Quem trabalha com Go sabe bem o quanto o ecossistema de ferramentas é fundamental para o desenvolvimento produtivo. Desde geradores de código como stringer até analisadores estáticos como staticcheck, essas ferramentas se tornaram parte essencial do fluxo de trabalho diário. No entanto, gerenciar essas dependências sempre foi um desafio - especialmente ao trabalhar em equipe.

Até agora, a solução padrão era o famoso padrão "tools.go" - um arquivo com imports em branco que não eram realmente usados no código, mas garantiam que as ferramentas fossem baixadas quando necessário. Era funcional, mas nunca pareceu uma solução elegante.

O Go 1.24, lançado em fevereiro de 2025, finalmente resolve esse problema introduzindo uma maneira oficial e elegante de gerenciar ferramentas: a nova funcionalidade go tool e a diretiva tool no arquivo go.mod. Esta mudança, representa uma melhoria significativa na experiência do desenvolvedor Go, permitindo um gerenciamento mais claro e eficiente das dependências de ferramentas.

O Problema Anterior

Antes do Go 1.24, para garantir que ferramentas como stringer, mockgen ou staticcheck estivessem disponíveis para todos da equipe, os desenvolvedores tipicamente usavam uma abordagem que ficou conhecida como o "padrão tools.go". Esse padrão envolvia:

Criar um arquivo chamado "tools.go" com restrições de build para que não fosse incluído na compilação normal
Adicionar imports em branco de todas as ferramentas necessárias
Usar go run para executar essas ferramentas quando necessário

//go:build tools
// +build tools

package tools

import (
    _ "golang.org/x/tools/cmd/stringer"
    _ "golang.org/x/vuln/cmd/govulncheck"
    _ "honnef.co/go/tools/cmd/staticcheck"
)

Embora funcional, esta abordagem tinha várias desvantagens:

Misturava ferramentas de desenvolvimento com dependências reais do código
Exigia comandos como go run golang.org/x/tools/cmd/stringer, que eram verbosos
Cada execução requeria uma recompilação da ferramenta, tornando o processo lento

A nova solução: go tool e a Diretiva tool

O Go 1.24 introduz uma solução elegante para esse problema com dois novos recursos principais:

A diretiva tool no arquivo go.mod
O comando go tool para executar ferramentas

Adicionando Ferramentas ao Projeto

Para adicionar uma ferramenta ao seu projeto, agora você pode simplesmente usar:

go get -tool golang.org/x/tools/cmd/stringer

Este comando baixa a ferramenta e adiciona uma diretiva tool ao seu arquivo go.mod:

module example.com/myproject
go 1.24

tool (
    golang.org/x/tools/cmd/stringer
)

Para versões específicas, basta adicionar o número da versão:

go get -tool honnef.co/go/tools/cmd/staticcheck@v0.5.1

Executando ferramentas

Após adicionar uma ferramenta, você pode executá-la facilmente com o comando go tool:

go tool stringer -type=Day enum.go

Ou para ferramentas com nomes ambíguos, use o caminho completo:

go tool golang.org/x/tools/cmd/stringer -type=Day enum.go

O comando go tool sem argumentos lista todas as ferramentas disponíveis, incluindo as nativas do Go e as definidas no seu módulo.

Caching de executáveis

Uma grande vantagem da nova abordagem é que os executáveis criados pelo go tool agora são armazenados em cache no Go build cache. Isso significa que as execuções repetidas são muito mais rápidas, pois a ferramenta não precisa ser recompilada a cada vez.

Benefícios da nova abordagem

A nova diretiva tool e o comando go tool oferecem diversos benefícios:

Separação clara: Ferramentas são claramente distinguidas das dependências de código
Sintaxe simplificada: Comandos mais curtos e intuitivos
Versionamento: Versões específicas das ferramentas podem ser bloqueadas facilmente
Melhor desempenho: Graças ao caching de executáveis
Consistência: Todas as pessoas da equipe usam exatamente as mesmas versões das ferramentas
Meta-padrão: O padrão tool permite operações em todas as ferramentas simultaneamente, como go get tool para atualizar todas elas

Exemplo do mundo real: Geração de Mocks para testes

Vamos ver um exemplo prático de como usar a nova funcionalidade go tool para gerar mocks para testes usando a ferramenta mockgen.

Passo 1: Adicionar mockgen ao projeto

# Adicionar mockgen como ferramenta
go get -tool github.com/golang/mock/mockgen

# Verificar se foi adicionada corretamente
cat go.mod

Nosso go.mod agora terá uma seção como:

tool (
    github.com/golang/mock/mockgen
)

Passo 2: Criar uma interface para mock

// service.go
package service

type UserService interface {
    GetUser(id string) (*User, error)
    CreateUser(user *User) error
}

type User struct {
    ID   string
    Name string
    Age  int
}

Passo 3: Gerar o mock usando go tool

go tool mockgen -source=service.go -destination=mocks/mock_service.go -package=mocks

Passo 4: Usar o mock em testes

// service_test.go
package service_test

import (
    "testing"

    "github.com/golang/mock/gomock"
    "example.com/myproject/mocks"
    "example.com/myproject/service"
)

func TestUserService(t *testing.T) {
    ctrl := gomock.NewController(t)
    defer ctrl.Finish()

    mockUserService := mocks.NewMockUserService(ctrl)

    // Configurar expectativas
    mockUser := &service.User{ID: "1", Name: "John", Age: 30}
    mockUserService.EXPECT().GetUser("1").Return(mockUser, nil)

    // Testar funcionalidade que usa o serviço
    user, err := mockUserService.GetUser("1")
    if err != nil {
        t.Errorf("Erro não esperado: %v", err)
    }
    if user.Name != "John" {
        t.Errorf("Nome esperado: John, obtido: %s", user.Name)
    }
}

Este exemplo demonstra como a nova funcionalidade go tool simplifica o processo de desenvolvimento, especialmente para tarefas como geração de código. A sintaxe é mais limpa e todo o processo fica mais transparente para todos os membros da equipe.

Considerações e Limitações

Apesar dos muitos benefícios, existem algumas considerações importantes ao usar a nova funcionalidade:

Versões compartilhadas de dependências: Ferramentas e código-fonte compartilham a mesma resolução de versão de dependências. Isso significa que, se uma ferramenta e seu código usam a mesma biblioteca mas com versões diferentes, pode haver conflitos.
Aumento do tamanho do cache: Como os executáveis são armazenados em cache, isso pode aumentar o tamanho total do cache de build.
Apenas ferramentas Go: Este mecanismo só funciona para ferramentas escritas em Go. Para ferramentas em outras linguagens, você ainda precisará de métodos alternativos.
Compatibilidade: A funcionalidade está disponível apenas no Go 1.24 ou posterior.

Conclusão

A nova funcionalidade go tool e a diretiva tool no Go 1.24 representam uma evolução significativa na forma como os desenvolvedores Go gerenciam ferramentas. Em vez de usar soluções improvisadas, agora temos uma abordagem oficial, elegante e eficiente.

Para desenvolvedores que trabalham em equipes ou em projetos complexos, essa mudança traz benefícios imediatos em termos de consistência, simplicidade e desempenho. É mais um exemplo de como a linguagem Go continua evoluindo de forma pragmática, mantendo a simplicidade e atendendo às necessidades reais dos desenvolvedores.

Se você ainda não experimentou o Go 1.24, esta é mais uma excelente razão para fazer a atualização e começar a aproveitar todo o potencial do novo gerenciamento de ferramentas.

Docker Model Runner: IA Local sem dor de cabeça

Rafael Pazini — Wed, 07 May 2025 13:55:14 +0000

Já imaginou poder rodar aqueles modelos de IA gigantes no seu computador tão facilmente quanto pedir um delivery de comida? Pois é isso que o Docker Model Runner faz! É como se fosse um Uber para modelos de IA: você "chama" o modelo, ele vem rapidinho, faz o trabalho e depois vai embora sem ocupar espaço quando você não precisa mais.

Lançado como beta no Docker Desktop 4.40, o Docker Model Runner é aquela novidade que faz você pensar: "Como vivíamos sem isso antes?". Se você já passou horas configurando ambientes para rodar IA localmente (aquele inferno de dependências que nunca termina), vai entender o porquê.

Conhecendo a ferramenta

Se você está começando agora e mal sabe a diferença entre um container e uma tupperware, relaxa! Vou explicar como se estivéssemos em um churrasco 🍗:

O Docker Model Runner é como um churrasqueiro profissional que você contrata para sua festa. Ele:

Traz sua própria churrasqueira (servidor de inferência)
Sabe exatamente como preparar cada tipo de carne (modelos de IA)
Limpa tudo quando termina (gerencia recursos)
E o melhor: você não precisa aprender a fazer churrasco para desfrutar dele!

Para quem já manja dos paranauês, o Docker Model Runner é um servidor de inferência baseado em llama.cpp que roda diretamente no host (não em containers) e expõe uma API compatível com OpenAI. Os modelos são distribuídos como artefatos OCI via Docker Hub e são carregados dinamicamente na memória apenas quando solicitados.

Pense no Docker Model Runner como um "docker-compose up" para sua IA local. Sem ficar se batendo com drivers, ambientes Python e bibliotecas incompatíveis.

A arquitetura é elegante: em vez de virtualizar o ambiente inteiro, o Model Runner aproveita os recursos nativos do host, incluindo aceleração de GPU, eliminando o overhead de containerização para tarefas de inferência intensivas.

A mágica por trás das cortinas

Quando você digita docker model run ai/llama3.2:1B-Q8_0 "Explique contêineres", o que acontece? É bem simples:

O Docker não inicia um container tradicional (surpresa!)
Em vez disso, faz uma chamada à API do servidor de inferência embutido no Docker Desktop
O servidor carrega o modelo em memória (se já não estiver carregado)
Executa a inferência usando recursos nativos do host
O modelo fica "de plantão" por 5 minutos e, se não receber novas solicitações, é descarregado.

Comandos básicos

Tá querendo experimentar? Aqui vai um guia rápido do tipo "Receitinha simples pro almoço":

# Verificando se está tudo funcionando
docker model status
# Deve responder algo tipo: "Docker Model Runner is running" (tudo certo!)

# Vendo quais modelos você já tem baixados
docker model list
# No início provavelmente vai estar vazio, tipo geladeira de estudante

# Baixando um modelo pequeno para teste
docker model pull ai/smollm2
# Esse modelo é pequeno, tipo um pãozinho de queijo - rápido e satisfatório!

# Executando o modelo com uma pergunta
docker model run ai/smollm2 "Explique o que é Docker como se eu tivesse 5 anos"
# Agora o modelo vai responder, provavelmente com algo sobre caixinhas mágicas...

# Quando não precisar mais, remova para liberar espaço
docker model rm ai/smollm2
# Tchau, modelo! Foi bom enquanto durou!

E agora você deve estar se perguntando: "Rafa, como eu consigo saber quais modelos estão disponíveis?"
Todos os modelos disponíveis estão no Docker Hub com o namespace ai: https://hub.docker.com/u/ai

Exemplos do mundo Real (nada de "Hello World" aqui!)

Agora vamos para a parte mais legal: chega de falação e vamos ver como isso é utilizado na vida real. Vou utilizar Go para criar os exemplos, mas você pode adaptar para qualquer linguagem.

Antes de começar (TL;DR)

Se você é do tipo que pula a introdução dos livros e vai direto para a ação, aqui está o guia estilo "miojo de 3 minutos":

Atualize o Docker Desktop para 4.40+
Abra as Configurações (aquele ícone de engrenagem)
Navegue até "Features in development" > aba "Beta" (onde as coisas legais ficam)
Ative "Enable Docker Model Runner" (clique no checkbox)
Bônus: Ative "Enable host-side TCP support" (para acessar via localhost, a porta padrão é 12434)
Clique em "Apply & Restart" (e vá pegar um café enquanto reinicia)
Teste com: docker model status (deve dizer que está rodando)

Como Escolher o Modelo Certo?

Escolher um modelo é como escolher um carro: depende do seu destino e do tamanho da sua garagem (ou, neste caso, da sua RAM).

Para iniciantes ou hardware limitado: Comece com modelos pequenos como ai/smollm2:360M-Q4_K_M ou ai/llama3.2:1B-Q8_0. São como carros compactos - cabem em qualquer garagem e consomem pouca gasolina.
Para equilíbrio entre qualidade e velocidade: Experimente modelos de tamanho médio como ai/llama3.2:8B-Q4_K_M. São como sedans de médio porte - bons para a maioria das situações do dia a dia.
Para tarefas complexas: Se você tem uma GPU poderosa, experimente modelos grandes como ai/llama3.2:70B-Q4_0. São como SUVs de luxo - mais lentos para estacionar, mas confortáveis para longas viagens.

O truque está no nome: o número antes do hífen é o tamanho (em bilhões de parâmetros) e o código após o Q indica o nível de quantização (Q8 é melhor qualidade que Q4, mas ocupa mais espaço).

Dica: Experimente antes de comprar

Não sabe qual modelo escolher? Faça como nas cafeterias chiques: peça uma amostra!

Caso 1: O atendente virtual

Cenário: Você trabalha em uma empresa que fabrica eletrodomésticos e precisa criar um atendente virtual que entenda os manuais dos produtos.

Problema da Vida Real: APIs externas são caras, serviços de nuvem expõem dados sensíveis e sua chefe está de olho no orçamento como um falcão.

Lembre-se: dependendo do volume de tráfego e de onde estiver rodando este modelo, as repostas podem ser lentas. Para ver o código completo do projeto, é só acessar o link do meu github.

Solução com Docker Model Runner:

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "log"
    "net/http"
)

// Request structures
type Message struct {
    Role    string `json:"role"`
    Content string `json:"content"`
}

type ModelRequest struct {
    Model    string    `json:"model"`
    Messages []Message `json:"messages"`
}

// Model response structures
type Choice struct {
    Message Message `json:"message"`
}

type ModelResponse struct {
    Choices []Choice `json:"choices"`
}

// API structures
type HelpRequest struct {
    Question string `json:"question"`
    Model    string `json:"model"`
}

type HelpResponse struct {
    Answer string `json:"answer"`
}

func main() {
    http.HandleFunc("/help", handleHelp)
    fmt.Println("Virtual assistant running on port 3000!")
    log.Fatal(http.ListenAndServe(":3000", nil))
}

func handleHelp(w http.ResponseWriter, r *http.Request) {
    // Check HTTP method
    if r.Method != http.MethodPost {
        http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
        return
    }

    // Decode request body
    var reqBody HelpRequest
    if err := json.NewDecoder(r.Body).Decode(&reqBody); err != nil {
        http.Error(w, "Error processing request", http.StatusBadRequest)
        return
    }

    // Use default model if not specified
    model := reqBody.Model
    if model == "" {
        model = "ai/llama3.2:1B-Q8_0"
    }

    // Prepare request for Docker Model Runner
    modelReq := ModelRequest{
        Model: model,
        Messages: []Message{
            {
                Role:    "system",
                Content: "You are an assistant specialized in LG brand appliances.",
            },
            {
                Role:    "user",
                Content: reqBody.Question,
            },
        },
    }

    // Convert to JSON
    reqJSON, err := json.Marshal(modelReq)
    if err != nil {
        http.Error(w, "Error preparing request", http.StatusInternalServerError)
        return
    }

    // Send request to Docker Model Runner
    resp, err := http.Post(
        "http://localhost:12434/engines/llama.cpp/v1/chat/completions",
        "application/json",
        bytes.NewBuffer(reqJSON),
    )
    if err != nil {
        http.Error(w, "Error querying the model", http.StatusInternalServerError)
        return
    }
    defer resp.Body.Close()

    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        http.Error(w, "Error reading model response", http.StatusInternalServerError)
        return
    }

    var modelResp ModelResponse
    if err := json.Unmarshal(body, &modelResp); err != nil {
        http.Error(w, "Error processing model response", http.StatusInternalServerError)
        return
    }

    if len(modelResp.Choices) == 0 {
        http.Error(w, "Model returned no response", http.StatusInternalServerError)
        return
    }

    response := HelpResponse{
        Answer: modelResp.Choices[0].Message.Content,
    }

    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(response)
}

Aqui criamos nosso servidor do assistente. Basicamente ele vai:

Receber uma requisição no endpoint /help
Usar o modelo que foi passado na requisição
Responder a pergunta que foi enviada pelo usuário

Este é um exemplo de requisição:

curl -X POST \
  http://localhost:3000/help \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Como eu reseto o Wi-Fi da minha televisão?",
    "model": "ai/llama3.2:1B-Q8_0"
  }'

E após nosso servidor processar a resposta, ele deve retornar algo assim:

{
  "answer": "**Resetação do Wi-Fi na Televisão LG**\n\n"+
    "Olá! Eu sou aqui para ajudá-lo a resolver qualquer problema que você "+
    "possa estar enfrentando com sua televisão LG.\n\n"+
    "Aqui estão os passos para resetar o Wi-Fi na sua televisão LG:\n\n"+

    "**Requisitos:**\n\n"+
    "- A televisão LG deve estar conectada à internet.\n"+
    "- Você deve ter acesso ao painel de controle da televisão ou à tela do aplicativo LG.\n\n"+

    "**Passos para resetar o Wi-Fi:**\n\n"+
    "1. **Localize o botão de reset**: Procure por um botão de reset na parte de trás da televisão. "+
       "Ele geralmente é um pequeno botão que se assemelha a um botão de \"reset\".\n"+
    "2. **Pressione o botão de reset**: Pressione o botão de reset várias vezes até que ele fique selado.\n"+
    "3. **Aguarde alguns segundos**: Aguarde alguns segundos até que a tela fique normal novamente.\n"+
    "4. **Conecte-se à internet**: Conecte-se à internet novamente.\n"+
    "5. **Ative o Wi-Fi**: Ative o Wi-Fi na televisão LG e faça login com seu nome de usuário e senha.\n\n"+

    "**Dicas adicionais:**\n\n"+
    "- Se você não conseguir encontrar o botão de reset, verifique se ele está localizado na "+
      "parte superior ou inferior da televisão.\n"+
    "- Se a televisão LG tiver um painel de controle, você pode verificar se a opção de reset está disponível.\n"+
    "- Se você estiver usando um aplicativo LG, verifique se a opção de reset está disponível no aplicativo.\n\n"+

    "**Dúvidas?**\n\n"+
    "Se você tiver alguma dúvida ou precisar de mais ajuda, não hesite em perguntar. "+
    "Estou aqui para ajudá-lo!\n\n"+
    "Espero que essas instruções tenham sido úteis. Se tiver mais alguma dúvida, "+
    "por favor, não hesite em perguntar."
}

Resultado: Um atendente virtual que roda 100% local, não expõe dados sensíveis, não depende da internet, e sua chefe adora porque não tem fatura mensal de API!

Conclusão

Limitações (Ninguém é Perfeito)

Como tudo na vida, o Docker Model Runner tem seus "poréns":

Não tem salvaguardas contra modelos gigantes - seu computador pode virar uma panela de pressão se você tentar rodar um modelo que não cabe na RAM.
É beta - então espere alguns bugs do tipo "funcionava ontem, hoje não".
Não roda em containers - ao contrário do Docker tradicional, roda diretamente no host.

O Futuro é Logo Ali

O Docker não está parado no tempo. Logo mais, o Model Runner vai ganhar:

Capacidade de personalizar e publicar seus próprios modelos (para os chefs de IA)
Integração com Docker Compose (para quem gosta de orquestrar seus serviços)
Parcerias com gigantes como Google e HuggingFace (mais modelos para brincar)

É como esperar a próxima temporada da sua série favorita - você sabe que vem coisa boa por aí!

Mais tempo codando, menos tempo configurando

O Docker Model Runner é como aquele amigo que aparece para ajudar na mudança com uma van, ferramentas e ainda traz pizza: resolve seu problema e ainda torna o processo agradável!

Para desenvolvedores brasileiros que sempre tiveram que se virar com criatividade (o famoso "jeitinho" no bom sentido), o Docker Model Runner é uma ferramenta que finalmente nos coloca no mesmo patamar dos grandes centros de tecnologia - podemos desenvolver aplicações de IA de ponta sem depender de APIs caras ou infraestrutura complexa.

Seja você um desenvolvedor querendo experimentar IA sem gastar uma fortuna em GPUs, ou um CTO procurando soluções para manter dados sensíveis dentro da empresa, o Docker Model Runner é aquele "pulo do gato" que faltava no seu arsenal técnico.

É isso meu povo e minha pova, deixem nos comentários se tiverem duvidas ou qualquer questão que eu possa ajudar 🥰

Go Concurrency: Como rodar múltiplas coisas ao mesmo tempo sem pirar

Rafael Pazini — Wed, 12 Feb 2025 14:54:55 +0000

Go foi projetado desde o início para facilitar a concorrência, tornando possível escrever código que executa várias tarefas ao mesmo tempo sem perder a cabeça. Neste artigo, vou te mostrar o que é concorrência, como funciona em Go e como você pode usar goroutines e channels para deixar seu código mais eficiente e responsivo.

Concorrência vs. Paralelismo: Qual é a Diferença?

Antes de tudo, vamos esclarecer um ponto: concorrência não é a mesma coisa que paralelismo.

Concorrência: quando seu código lida com múltiplas tarefas ao mesmo tempo, alternando entre elas conforme necessário.
Paralelismo: quando seu código executa várias tarefas ao mesmo tempo, literalmente ao mesmo tempo, geralmente em múltiplos núcleos de CPU.

Pensa assim: você está cozinhando um jantar. Enquanto a água ferve (uma tarefa), você pica os legumes (outra tarefa). Isso é concorrência. Agora, se você tivesse um clone seu picando os legumes enquanto você ferve a água, isso seria paralelismo.

Goroutines: Executando Funções Concorrentemente

Em Go, criar uma função concorrente é incrivelmente fácil. Basta colocar go antes da chamada da função e pronto, ela roda em segundo plano sem te incomodar.

Exemplo simples de goroutine:

package main

import (
    "fmt"
    "time"
)

func digaOla() {
    fmt.Println("Olá, mundo!")
}

func main() {
    go digaOla() // Rodando a função como goroutine
    time.Sleep(time.Second) // Esperando um pouco para ver a saída
}

Aqui, digaOla() é executada de forma concorrente, mas como o programa principal pode terminar antes que ela rode, colocamos um time.Sleep(time.Second) só pra garantir que dê tempo de ver a saída. Claro que, em código real, a gente usaria algo mais robusto, como channels, para sincronização.

Channels: Conversando Entre Goroutines

Goroutines são legais, mas como elas conversam entre si? Em Go, usamos channels, que funcionam como uma esteira de produção: uma goroutine coloca um dado de um lado e outra goroutine pega do outro.

Unbuffered Channels: Mensagens "Na Hora"

Os unbuffered channels são como passar um recado para um amigo pessoalmente: você fala e ele escuta na mesma hora.

package main

import "fmt"

func main() {
    mensagens := make(chan string) // Criando um channel de strings

    go func() {
        mensagens <- "Olá, Go!"
    }()

    fmt.Println(<-mensagens) // Recebendo a mensagem do channel
}

Aqui, a goroutine anônima envia uma mensagem pelo channel, e a main recebe e imprime. O channel bloqueia até que haja um receptor do outro lado, garantindo sincronização.

Buffered Channels: Guardando Mensagens

Buffered channels são como um correio: você pode colocar mensagens na caixa antes que o carteiro as retire.

package main

import "fmt"

func main() {
    numeros := make(chan int, 3) // Criando um buffered channel com capacidade 3

    numeros <- 1
    numeros <- 2
    numeros <- 3

    fmt.Println(<-numeros) // 1
    fmt.Println(<-numeros) // 2
    fmt.Println(<-numeros) // 3
}

Aqui, o channel pode armazenar até 3 valores sem bloquear. Se tentarmos enviar um 4º valor antes de consumir algum, o programa trava até que haja espaço.

Select: Lidando com Múltiplos Channels

O comando select em Go permite ouvir vários channels ao mesmo tempo, tipo um garçom atendendo várias mesas ao mesmo tempo.

package main

import (
    "fmt"
    "time"
)

func main() {
    canal1 := make(chan string)
    canal2 := make(chan string)

    go func() {
        time.Sleep(2 * time.Second)
        canal1 <- "Mensagem do canal 1"
    }()

    go func() {
        time.Sleep(1 * time.Second)
        canal2 <- "Mensagem do canal 2"
    }()

    select {
    case msg1 := <-canal1:
        fmt.Println(msg1)
    case msg2 := <-canal2:
        fmt.Println(msg2)
    }
}

Aqui, select escolhe o primeiro channel que estiver pronto, garantindo que a resposta mais rápida seja processada primeiro.

Concorrência na Vida Real

Agora que você já viu como usar goroutines e channels, aqui estão alguns exemplos do mundo real onde a concorrência brilha:

Servidores Web: Cada requisição é tratada em uma goroutine separada, evitando travamentos.
Scrapers de Dados: Se você precisar buscar informações de vários sites, pode fazer isso concorrentemente e acelerar o processo.
Jogos Multiplayer: Goroutines podem gerenciar o estado de cada jogador e enviar atualizações rapidamente.

Conclusão

Go torna a concorrência fácil e eficiente, permitindo criar aplicações escaláveis e responsivas sem dores de cabeça. Ao dominar goroutines, channels e select, você consegue construir sistemas que aproveitam melhor o hardware e evitam travamentos.

Então, da próxima vez que precisar rodar várias coisas ao mesmo tempo, lembre-se: goroutines são seus amigos, e channels são a melhor forma de manter a conversa em ordem! 🚀

Dominando o Docker Bake: Simplificando Builds Complexos

Rafael Pazini — Wed, 05 Feb 2025 04:24:27 +0000

Com o aumento da complexidade nas aplicações modernas, especialmente em ambientes que utilizam monorepos ou múltiplos contêineres, o gerenciamento de builds no Docker pode rapidamente se tornar uma tarefa desafiadora. Felizmente, o Docker Bake surgiu como uma solução poderosa para simplificar, otimizar e acelerar esses processos. Neste post, vamos explorar o que é o Docker Bake, como utilizá-lo de forma eficaz, e alguns exemplos práticos que vão desde configurações básicas até recursos avançados.

O que é o Docker Bake?

O Docker Bake é uma ferramenta que permite definir e executar builds de imagens Docker de forma declarativa e eficiente. Ele é especialmente útil para cenários onde você precisa construir múltiplas imagens simultaneamente, compartilhar configurações entre diferentes ambientes ou simplificar comandos de build complexos.

Vantagens do Docker Bake:

Simplicidade: Abstrai configurações complexas em um comando simples.
Flexibilidade: Suporte para funções customizadas, matrices, e muito mais.
Consistência: Compartilhamento fácil de configurações com o time.
Performance: Builds paralelos para acelerar workflows.

Como Funciona o Docker Bake?

O Docker Bake usa arquivos de configuração em formato HCL (docker-bake.hcl) ou JSON (docker-bake.json) para definir targets, variáveis, e estratégias de caching. É como se fosse um "Makefile" para imagens Docker, mas com muito mais poder e simplicidade.

Estrutura Básica de um Arquivo `docker-bake.hcl`

variable "TAG" {
  default = "latest"
}

target "app" {
  context = "."
  dockerfile = "Dockerfile"
  tags = ["meuapp:${TAG}"]
}

target "app-prod" {
  inherits = ["app"]
  args = {
    ENV = "production"
  }
  tags = ["meuapp:prod"]
}

Com esse arquivo, você pode rodar:

docker buildx bake app-prod

Isso constrói a imagem com o tag meuapp:prod e a variável de ambiente ENV=production.

Recursos Avançados do Docker Bake

1. Matrix de Targets

Se você precisa construir a mesma imagem para diferentes arquiteturas ou ambientes, o Docker Bake permite definir matrices para automatizar esse processo.

variable "PLATFORMS" {
  default = ["linux/amd64", "linux/arm64"]
}

target "multiarch-app" {
  context = "."
  dockerfile = "Dockerfile"
  platforms = PLATFORMS
  tags = ["meuapp:multiarch"]
}

Agora, com um único comando, você cria imagens para múltiplas arquiteturas:

docker buildx bake multiarch-app

2. Entitlements (Permissões Especiais)

Com o Bake, você pode controlar permissões especiais usando o flag --allow. Isso é útil para builds que precisam de acesso a recursos como o sistema de arquivos host ou rede.

docker buildx bake app-prod --allow network.host --allow fs.read=/dados/externos

Essa abordagem melhora a segurança, garantindo que apenas as permissões necessárias sejam concedidas.

3. Deduplicacão de Contextos

Se você está construindo várias imagens que compartilham o mesmo contexto, o Bake agora deduplica automaticamente essas transferências, acelerando significativamente o tempo de build.

Antes, era necessário definir contextos nomeados manualmente:

group "apps" {
  targets = ["app1", "app2"]
}

target "app1" {
  context = "."
  dockerfile = "Dockerfile.app1"
}

target "app2" {
  context = "."
  dockerfile = "Dockerfile.app2"
}

Agora, o Bake otimiza isso automaticamente sem necessidade de ajustes adicionais.

4. Validação de Variáveis

Assim como no Terraform, o Docker Bake agora permite validar variáveis para garantir que os valores fornecidos sejam adequados.

variable "VERSION" {
  validation {
    condition = VERSION != ""
    error_message = "A variável VERSION é obrigatória."
  }
  validation {
    condition = strlen(VERSION) > 3
    error_message = "A VERSION deve ter mais de 3 caracteres."
  }
}

Se a variável VERSION não for definida ou for muito curta, o Bake retornará um erro descritivo.

5. Atributos Componíveis

A partir da versão GA do Bake, atributos como cache-from, output, e secret podem ser definidos como objetos estruturados, facilitando a reutilização e composição.

target "app" {
  cache-from = [
    { type = "registry", ref = "usuario/app:cache" },
    { type = "local", src = "./cache" }
  ]

  output = [
    { type = "local", dest = "./build" },
    { type = "oci", dest = "./app.oci" }
  ]
}

Casos de Uso Reais

1. Monorepos

Se você trabalha com um monorepo contendo diversos serviços, o Docker Bake facilita a construção de todos os serviços de forma paralela e otimizada.

group "servicos" {
  targets = ["api", "frontend", "worker"]
}

target "api" {
  context = "./api"
  dockerfile = "Dockerfile"
}

target "frontend" {
  context = "./frontend"
  dockerfile = "Dockerfile"
}

target "worker" {
  context = "./worker"
  dockerfile = "Dockerfile"
}

Rodando:

docker buildx bake servicos

2. Microservices Distribuídos

Mesmo que você não utilize um monorepo, é possível gerenciar builds de múltiplos microserviços que residem em diferentes repositórios ou diretórios.

target "auth-service" {
  context = "../auth-service"
  dockerfile = "Dockerfile"
  tags = ["empresa/auth:latest"]
}

target "payment-service" {
  context = "../payment-service"
  dockerfile = "Dockerfile"
  tags = ["empresa/payment:latest"]
}

group "microservices" {
  targets = ["auth-service", "payment-service"]
}

Com isso, você pode construir todos os microserviços com um único comando:

docker buildx bake microservices

3. Execução de Testes Automatizados

O Docker Bake também é útil para pipelines de CI/CD, facilitando a execução de testes automatizados.

target "test" {
  context = "."
  dockerfile = "Dockerfile.test"
  args = {
    TEST_ENV = "ci"
  }
  output = ["type=local,dest=./test-results"]
}

Rodando o comando abaixo, você dispara o ambiente de testes:

docker buildx bake test

Isso permite a integração fácil com ferramentas de CI como GitHub Actions ou GitLab CI.

4. Integração com Docker Compose

Você também pode usar o Bake junto com o Docker Compose:

docker buildx bake --file docker-compose.yml

Isso permite reaproveitar suas configurações de services do Compose para gerenciar builds.

Conclusão

O Docker Bake é uma ferramenta essencial para quem busca simplificar e otimizar workflows de build no Docker. Com recursos como matrices de targets, deduplicacção de contextos, permissões configuráveis e validação de variáveis, ele oferece um ambiente robusto para desenvolvedores e times de DevOps.

Se você ainda está lutando com comandos complexos e builds lentos, é hora de dar uma chance ao Docker Bake e transformar sua experiência de desenvolvimento.

Recursos Adicionais

Experimente e compartilhe suas experiências nos comentários!

DEV Community: Rafael Pazini

Meu Claude tem memória agora: e foi mais simples do que parece

As três camadas de memória

O que o auto-dream faz na prática

O que eu já tinha e não sabia

A solução: o /retro simplificado

A observabilidade pelo Obsidian

O que não implementei (e por quê)

Como fica o loop na prática

Como começar

Docker Compose + tmpfs: Armazenamento efêmero que sua aplicação

O que é tmpfs, afinal?

Configuração básica

Configuração avançada

Casos de uso com Go: onde isso realmente brilha

1. Cache de build Go

2. Uploads temporários em APIs Go

3. Banco de dados para testes

4. Segurança: filesystem read-only com exceções tmpfs

Benchmark: vendo a diferença

Sizing dinâmico por ambiente

Monitorando o uso

Exemplos do mundo real

LocalStack + tmpfs: desenvolvimento AWS sem custo e sem lentidão

Imagens scratch + tmpfs: a combinação mais segura que você pode fazer

MCP server + tmpfs: cache de respostas de API sem persistência

Quando NÃO usar tmpfs

O impacto real no dia a dia

Vale a pena?

Docker Compose para Agentes de IA: O que realmente mudou (e o que você precisa saber agora)

O que mudou no Compose

O ecossistema expandiu bastante

Gordon: o agente que o Docker não estava avisando que ia lançar

MCP Gateway e MCP Catalog: o que isso muda na prática

Model Runner: o que evoluiu desde o lançamento

Docker Compose v5 e o Go SDK

Cloud Run e o que está por vir

Boas práticas que o tempo confirmou

Quando usar (e quando esperar)

O ponto central

Go 1.26: GreenteaGC por padrão, 'new' com superpoderes e outras melhorias que você vai querer testar

GreenteaGC: De Experimento a Padrão

new com Expressão: Finalmente

Tipos Genéricos Autorreferenciais

Alocações Especializadas por Tamanho

cgo 30% Mais Rápido

crypto/hpke: Criptografia Moderna no stdlib

Experimentos que Vale Ativar Agora

Tooling: go fix Ficou Esperto

Vale Atualizar Agora?

Docker cagent: Como orquestrar agentes IA com YAML (e por que isso muda tudo)

O Problema Que o cagent Resolve

Arquitetura e Funcionalidades Principais

Configuração Declarativa com YAML

Orquestração Multi-Agente Inteligente

Suporte a Múltiplos Provedores de IA

Exemplos Práticos de Uso

Caso 1: Agente de Revisão de Código

Caso 2: Sistema de Documentação Automática

Caso 3: Agente de Monitoramento e Alertas

Integração com Docker Hub

Performance e Escalabilidade

Execução Local vs Nuvem

Otimização de Custos

Considerações Técnicas e Implementação

Gerenciamento de Estado e Memória

Integração com CI/CD

Monitoramento e Observabilidade

Primeiros Passos e Implementação

Instalação

Seu Primeiro Agente

Projeto Prático: Bot de Suporte Técnico

Por Que Isso É Revolucionário

Próximos passos

Go 1.25: JSON v2 e Novo GC

Por que o JSON v2 existe?

O que mudou na implementação do JSON v2

Arquitetura otimizada para Menos Alocações

Parser não-sequencial e streaming nativo

Otimizações específicas para tipos comuns

A solução: o `/retro` simplificado

`new` com Expressão: Finalmente

`crypto/hpke`: Criptografia Moderna no stdlib