Joao Oliveira – Joao Oliveira

Construindo uma API em Go para gerenciar arquivos no Amazon S3

Fri, 09 Jan 2026 00:00:00 +0000

Quando decidi criar meu blog, escolhi o Amazon S3 para hospedar as imagens dos posts. A decisão foi prática (S3 é confiável, barato e escala bem), mas eu também vi ali uma oportunidade: usar um problema real do dia a dia para aprofundar minha fluência no ecossistema AWS, especialmente em segurança, automação e integrações.

Depois de ter criado um programa em Go que me permite otimizar e converter para WebP, o qual detalhei nesse artigo, resolvi criar uma API também em Go, que me permite gerenciar minha conta na AWS, com isso posso fazer upload individual ou múltiplo de arquivos, gerenciamento de buckets, listagem inteligente e downloads eficientes via streaming.

Foi aí que surgiu esta API: uma aplicação em Go que me permite gerenciar arquivos e buckets no S3 com um fluxo pensado para produtividade, upload único ou múltiplo, listagem paginada, download via streaming e geração de URL temporária (presigned URL) para acesso seguro.

Para garantir agilidade no dia a dia, a aplicação é totalmente containerizada com Docker. Assim, eu subo o container e uso os endpoints (que já deixo salvos no Apidog). A cada upload, recebo instantaneamente o link final do arquivo, pronto para colar no post. Esse é o fluxo “fácil e rápido” que eu queria.

O que essa API faz

De forma resumida, esta API cobre:

Uploads individuais e múltiplos (com concorrência).
Listagem paginada de objetos com metadados úteis.
Download via streaming, evitando carregar arquivos inteiros na memória da API.
Presigned URLs para acesso temporário e seguro a buckets privados.
Gerenciamento de buckets (criar, listar, estatísticas, esvaziar e remover).

Arquitetura e Estrutura do Projeto

Estruturei o projeto seguindo as recomendações do Go Standards Project Layout. Essa organização, inspirada em Clean Architecture, permite que a aplicação nasça robusta, facilitando a evolução de funcionalidades e a manutenção a longo prazo.

Como cada parte se conecta

Uma forma simples de entender a arquitetura é imaginar um fluxo:

Handler (HTTP): traduz protocolo, valida o mínimo e devolve resposta.
Service: aplica regras, validações, segurança, concorrência e timeouts.
Repository (interface): contrato de armazenamento.
S3 Repository (implementação): detalhes de integração com AWS SDK.

Estrutura de diretórios

s3-api/
├── .github/
│ └── workflows/ # CI: pipelines (testes, lint, build) no GitHub Actions
├── cmd/
│ └── api/
│ └── main.go # Bootstrap: carrega config, inicializa dependências e sobe o HTTP server
├── internal/
│ ├── config/ # Configuração centralizada: env vars tipadas + defaults
│ ├── middleware/ # Middlewares HTTP: logging, timeout, recovery, etc.
│ └── upload/ # Módulo de domínio (arquivos e buckets no S3)
│ ├── entity.go # Entidades e DTOs de resposta (modelos do domínio)
│ ├── errors.go # Erros de domínio (sem acoplamento a HTTP)
│ ├── repository.go # Contrato (interface) de storage
│ ├── s3_repository.go # Implementação do contrato usando AWS SDK v2
│ ├── service.go # Regras de negócio: validações, concorrência, timeouts
│ ├── handler.go # HTTP handlers: traduz request/response e chama o Service
│ └── service_test.go # Testes unitários do Service (com mocks do Repository)
├── .env # Config local (NUNCA versionar; usar .gitignore)
├── Dockerfile # Build multi-stage (binário enxuto)
└── docker-compose.yml # Ambiente local: sobe API com env/ports

Decisões importantes nessa estrutura

cmd/api/main.go: Aqui aplicamos a Injeção de Dependência. O main cria o cliente da AWS, o repositório e o serviço, conectando-os. Se amanhã quisermos mudar o S3 para um banco local, mudamos apenas uma linha aqui.
internal/middleware/: Implementamos um middleware de Logging estruturado (usando slog) e um de Timeout, garantindo que nenhuma requisição fique pendurada infinitamente, protegendo a saúde da aplicação.
internal/upload/service.go: É aqui que usamos concorrência avançada com errgroup. Ao fazer uploads múltiplos, o serviço dispara várias goroutines para falar com o S3 em paralelo, reduzindo drasticamente o tempo de resposta.
internal/upload/errors.go: Em vez de retornar strings genéricas, usamos erros tipados. Isso permite que o Handler identifique se deve retornar um 400 Bad Request ou um 404 Not Found de forma elegante.

Endpoints

A API foi dividida em dois grandes grupos: gerenciamento de Arquivos e de Buckets.

Files

Method	Endpoint	Description
POST	/api/v1/upload	Upload de 1 arquivo
POST	/api/v1/upload-multiple	Upload múltiplo
GET	/api/v1/list	Listagem paginada
GET	/api/v1/download	Download via streaming
GET	/api/v1/presign	Gera URL temporária (presigned)
DELETE	/api/v1/delete	Remove o objeto do bucket

Buckets

Method	Endpoint	Description
GET	/api/v1/buckets/list	Lista buckets da conta
POST	/api/v1/buckets/create	Cria bucket
GET	/api/v1/buckets/stats	Estatísticas
DELETE	/api/v1/buckets/delete	Remove o bucket
DELETE	/api/v1/buckets/empty	Esvazia bucket

Pontos de destaque e decisões técnicas

Decisões que mais impactam o uso real da API

UUID v7 para nomes de arquivos

Nos uploads eu uso UUID v7 para renomear os arquivos. Além de evitar colisões e exposição de nomes originais, o v7 preserva ordenação temporal. Isso ajuda na organização no S3, facilita auditoria e deixa o caminho aberto para evolução futura (por exemplo, indexação em banco sem perder ordenação).

Streaming para evitar picos de memória

No download, a ideia é manter o consumo de RAM estável. Em vez de “baixar tudo e depois devolver”, eu trato como um fluxo: os dados saem do S3 e vão para o cliente sem precisar virar um buffer gigante dentro da API.

Validação real de tipo de arquivo (MIME)

Extensão é fácil de falsificar. Por isso, em vez de confiar no .jpg/.png, eu valido o conteúdo do arquivo (header) para identificar o tipo real. Isso reduz a chance de subir conteúdo malicioso disfarçado como imagem.

Timeouts como proteção de recursos

Como a API depende de serviços externos (S3), eu não quero requisições “penduradas”. Timeouts impedem consumo excessivo de goroutines e conexões quando a rede está ruim ou quando há lentidão do provedor.

Inicializando o projeto

O primeiro passo é preparar o ambiente de desenvolvimento. O Go utiliza o sistema de módulos (go mod) para gerenciar dependências, o que garante que o projeto seja reprodutível em qualquer máquina.

# Criação da pasta raiz e entrada no diretório
mkdir s3-api && cd s3-api

# Inicialização do módulo (substitua pelo seu repositório se necessário)
go mod init github.com/JoaoOliveira889/s3-api

# Criação da árvore de diretórios seguindo o Go Standard Layout
mkdir -p cmd/api internal/upload internal/config internal/middleware

Gerenciamento de Dependências

Eu uso o AWS SDK for Go v2 e algumas bibliotecas para dar robustez ao projeto (roteamento HTTP, carregamento de env, UUID, testes). A ideia é manter um conjunto enxuto e bem justificado, evitando dependências desnecessárias.

# Core do SDK e gerenciamento de configurações/credenciais
go get github.com/aws/aws-sdk-go-v2
go get github.com/aws/aws-sdk-go-v2/config

# Serviço específico do S3
go get github.com/aws/aws-sdk-go-v2/service/s3

# Gin Gonic: Framework HTTP de alta performance
go get github.com/gin-gonic/gin

# GoDotEnv: Para carregar variáveis de ambiente do arquivo .env
go get github.com/joho/godotenv

# UUID: Para geração de identificadores únicos v7
go get github.com/google/uuid

# Testify: Para facilitar a criação de asserções e mocks nos testes
go get github.com/stretchr/testify

Camada de Domínio

Aqui entram as entidades e os contratos. O ponto central é: o domínio descreve o que o sistema faz, sem acoplamento ao S3 em si.

Entidades

As entidades representam os dados principais da aplicação: arquivos, metadados para listagem, estatísticas de bucket e paginação.

package upload

import (
 "io"
 "time"
)

type File struct {
 Name string `json:"name"`//nome final do objeto no storage
 URL string `json:"url"`//URL resultante após upload
 Content io.ReadSeekCloser `json:"-"`//Content não é serializado em JSON porque representa o stream do arquivo
 Size int64 `json:"size"`
 ContentType string `json:"content_type"`
}

type FileSummary struct {
 Key string `json:"key"`//chave completa do objeto no S3
 URL string `json:"url"`
 Size int64 `json:"size_bytes"`
 HumanReadableSize string `json:"size_formatted"`
 Extension string `json:"extension"`
 StorageClass string `json:"storage_class"`
 LastModified time.Time `json:"last_modified"`
}

type BucketStats struct {
 BucketName string `json:"bucket_name"`
 TotalFiles int `json:"total_files"`
 TotalSizeBytes int64 `json:"total_size_bytes"`
 TotalSizeFormatted string `json:"total_size_formatted"`
}

type BucketSummary struct {
 Name string `json:"name"`
 CreationDate time.Time `json:"creation_date"`
}

type PaginatedFiles struct {
 Files []FileSummary `json:"files"`
 NextToken string `json:"next_token,omitempty"`//token de continuação (pagination token)
}

Interface do Repositório

O repositório define um contrato de armazenamento. Assim, o Service não “sabe” que é S3. Ele só sabe que existe uma implementação capaz de armazenar, listar, baixar e deletar.

Nota: ao trabalhar com stream no upload/download, a API evita carregar arquivos inteiros em memória, mantendo o consumo de RAM muito mais previsível.

package upload

import (
 "context"
 "io"
 "time"
)

// Repository define o contrato de storage.
type Repository interface {
 // Upload armazena o arquivo no bucket e retorna a URL final do objeto.
 Upload(ctx context.Context, bucket string, file *File) (string, error)

 // GetPresignURL gera uma URL temporária para download seguro
 GetPresignURL(ctx context.Context, bucket, key string, expiration time.Duration) (string, error)

 // Download retorna um stream (io.ReadCloser) para permitir streaming sem carregar tudo em memória.
 Download(ctx context.Context, bucket, key string) (io.ReadCloser, error)

 // List retorna uma página de arquivos usando token de continuação.
 List(ctx context.Context, bucket, prefix, token string, limit int32) (*PaginatedFiles, error)

 // Delete remove um objeto específico do bucket.
 Delete(ctx context.Context, bucket string, key string) error

 // CheckBucketExists verifica se o bucket existe e está acessível.
 CheckBucketExists(ctx context.Context, bucket string) (bool, error)

 // CreateBucket cria um bucket (geralmente com validações prévias na camada de Service).
 CreateBucket(ctx context.Context, bucket string) error

 // ListBuckets lista todos os buckets disponíveis na conta.
 ListBuckets(ctx context.Context) ([]BucketSummary, error)

 // GetStats agrega estatísticas do bucket
 GetStats(ctx context.Context, bucket string) (*BucketStats, error)

 // DeleteAll remove todos os objetos do bucket
 DeleteAll(ctx context.Context, bucket string) error

 // DeleteBucket remove o bucket
 DeleteBucket(ctx context.Context, bucket string) error
}

Camada de Infraestrutura

Com o contrato definido, eu crio a implementação concreta para falar com a AWS. Aqui o objetivo é traduzir as necessidades do domínio para chamadas do AWS SDK v2.

package upload

import (
 "context"
 "fmt"
 "io"
 "path/filepath"
 "strings"
 "time"

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

type S3Repository struct {
 client *s3.Client
 region string
}

func NewS3Repository(client *s3.Client, region string) Repository {
 return &S3Repository{
 client: client,
 region: region,
 }
}

func (r *S3Repository) Upload(ctx context.Context, bucket string, file *File) (string, error) {
 input := &s3.PutObjectInput{
 Bucket: aws.String(bucket),
 Key: aws.String(file.Name),
 Body: file.Content, //stream: evita carregar o arquivo inteiro em memória
 }

 _, err := r.client.PutObject(ctx, input)
 if err != nil {
 return "", fmt.Errorf("failed to upload: %w", err)
 }

 // URL direta
 return fmt.Sprintf("https://%s.s3.%s.amazonaws.com/%s", bucket, r.region, file.Name), nil
}

func (r *S3Repository) List(ctx context.Context, bucket, prefix, token string, limit int32) (*PaginatedFiles, error) {
 input := &s3.ListObjectsV2Input{
 Bucket: aws.String(bucket),
 Prefix: aws.String(prefix),
 ContinuationToken: aws.String(token),
 MaxKeys: aws.Int32(limit),
 }

 // No SDK, token vazio deve ser nil para evitar request com token inválido.
 if token == "" {
 input.ContinuationToken = nil
 }

 output, err := r.client.ListObjectsV2(ctx, input)
 if err != nil {
 return nil, fmt.Errorf("failed to list objects: %w", err)
 }

 var files []FileSummary
 for _, obj := range output.Contents {
 key := aws.ToString(obj.Key)
 size := aws.ToInt64(obj.Size)
 files = append(files, FileSummary{
 Key: key,
 Size: size,
 HumanReadableSize: formatBytes(size),
 StorageClass: string(obj.StorageClass),
 LastModified: aws.ToTime(obj.LastModified),
 Extension: strings.ToLower(filepath.Ext(key)),
 URL: fmt.Sprintf("https://%s.s3.%s.amazonaws.com/%s", bucket, r.region, key),
 })
 }

 next := ""
 if output.NextContinuationToken != nil {
 next = *output.NextContinuationToken
 }

 return &PaginatedFiles{Files: files, NextToken: next}, nil
}

func (r *S3Repository) Delete(ctx context.Context, bucket, key string) error {
 _, err := r.client.DeleteObject(ctx, &s3.DeleteObjectInput{
 Bucket: aws.String(bucket),
 Key: aws.String(key),
 })
 return err
}

func (r *S3Repository) Download(ctx context.Context, bucket, key string) (io.ReadCloser, error) {
 output, err := r.client.GetObject(ctx, &s3.GetObjectInput{
 Bucket: aws.String(bucket),
 Key: aws.String(key),
 })
 if err != nil {
 return nil, err
 }

 // Retorna o Body como stream para o Handler fazer io.Copy direto na resposta.
 return output.Body, nil
}

func (r *S3Repository) GetPresignURL(ctx context.Context, bucket, key string, exp time.Duration) (string, error) {
 // Presign client gera URLs temporárias sem precisar tornar o objeto público.
 pc := s3.NewPresignClient(r.client)
 req, err := pc.PresignGetObject(ctx, &s3.GetObjectInput{
 Bucket: aws.String(bucket),
 Key: aws.String(key),
 }, s3.WithPresignExpires(exp))
 if err != nil {
 return "", err
 }
 return req.URL, nil
}

func (r *S3Repository) CheckBucketExists(ctx context.Context, bucket string) (bool, error) {
 _, err := r.client.HeadBucket(ctx, &s3.HeadBucketInput{Bucket: aws.String(bucket)})
 if err != nil {
 return false, nil
 }
 return true, nil
}

func (r *S3Repository) CreateBucket(ctx context.Context, bucket string) error {
 _, err := r.client.CreateBucket(ctx, &s3.CreateBucketInput{Bucket: aws.String(bucket)})
 return err
}

func (r *S3Repository) ListBuckets(ctx context.Context) ([]BucketSummary, error) {
 out, err := r.client.ListBuckets(ctx, &s3.ListBucketsInput{})
 if err != nil {
 return nil, err
 }
 var res []BucketSummary
 for _, b := range out.Buckets {
 res = append(res, BucketSummary{Name: aws.ToString(b.Name), CreationDate: aws.ToTime(b.CreationDate)})
 }
 return res, nil
}

func (r *S3Repository) DeleteBucket(ctx context.Context, bucket string) error {
 _, err := r.client.DeleteBucket(ctx, &s3.DeleteBucketInput{Bucket: aws.String(bucket)})
 return err
}

func (r *S3Repository) DeleteAll(ctx context.Context, bucket string) error {
 out, err := r.client.ListObjectsV2(ctx, &s3.ListObjectsV2Input{Bucket: aws.String(bucket)})
 if err != nil || len(out.Contents) == 0 {
 return err
 }

 var objects []types.ObjectIdentifier
 for _, obj := range out.Contents {
 objects = append(objects, types.ObjectIdentifier{Key: obj.Key})
 }
 _, err = r.client.DeleteObjects(ctx, &s3.DeleteObjectsInput{
 Bucket: aws.String(bucket),
 Delete: &types.Delete{Objects: objects},
 })
 return err
}

func (r *S3Repository) GetStats(ctx context.Context, bucket string) (*BucketStats, error) {
 out, err := r.client.ListObjectsV2(ctx, &s3.ListObjectsV2Input{Bucket: aws.String(bucket)})
 if err != nil {
 return nil, err
 }
 var totalSize int64
 for _, obj := range out.Contents {
 totalSize += aws.ToInt64(obj.Size)
 }
 return &BucketStats{
 BucketName: bucket,
 TotalFiles: int(len(out.Contents)),
 TotalSizeBytes: totalSize,
 TotalSizeFormatted: formatBytes(totalSize),
 }, nil
}

func formatBytes(b int64) string {
 const unit = 1024
 if b < unit {
 return fmt.Sprintf("%d B", b)
 }
 div, exp := int64(unit), 0
 for n := b / unit; n >= unit; n /= unit {
 div *= unit
 exp++
 }
 return fmt.Sprintf("%.1f %cB", float64(b)/float64(div), "KMGTPE"[exp])
}

Destaques técnicos na Infraestrutura

Contexto (context.Context): operações de rede respeitam cancelamento e timeout; se a requisição cair, eu evito trabalho inútil e consumo de recursos.
Paginação eficiente: essencial para buckets grandes; o cliente navega sem sobrecarregar a API.
Presigned URLs: acesso temporário e seguro a bucket privado sem expor o bucket publicamente.
Apresentação de dados: formatar tamanhos e metadados melhora muito a experiência de quem consome a API.

Camada de Serviço

Nesta camada fica a orquestração: validações, regras de negócio, timeouts e concorrência.

Um detalhe que eu gosto aqui: a interface Service expõe o “o que a aplicação faz”, enquanto a implementação concreta fica privada, forçando o uso de um construtor (factory). Isso ajuda a manter o design consistente e controlado.

package upload

import (
 "context"
 "fmt"
 "io"
 "log/slog"
 "net/http"
 "path/filepath"
 "regexp"
 "strings"
 "time"

 "github.com/google/uuid"
 "golang.org/x/sync/errgroup"
)

type Service interface {
 UploadFile(ctx context.Context, bucket string, file *File) (string, error)
 UploadMultipleFiles(ctx context.Context, bucket string, files []*File) ([]string, error)
 GetDownloadURL(ctx context.Context, bucket, key string) (string, error)
 DownloadFile(ctx context.Context, bucket, key string) (io.ReadCloser, error)
 ListFiles(ctx context.Context, bucket, ext, token string, limit int) (*PaginatedFiles, error)
 DeleteFile(ctx context.Context, bucket string, key string) error
 GetBucketStats(ctx context.Context, bucket string) (*BucketStats, error)
 CreateBucket(ctx context.Context, bucket string) error
 ListAllBuckets(ctx context.Context) ([]BucketSummary, error)
 DeleteBucket(ctx context.Context, bucket string) error
 EmptyBucket(ctx context.Context, bucket string) error
}

const (
 uploadTimeout = 60 * time.Second
 deleteTimeout = 5 * time.Second
 maxBucketNameLength = 63
 minBucketNameLength = 3
)

var (
 // S3 bucket names seguem regras de DNS (min/max e charset). Regex cobre o padrão geral.
 bucketDNSNameRegex = regexp.MustCompile(`^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$`)

 // Allowlist: valida tipo real do arquivo (MIME detectado) em vez de confiar na extensão.
 allowedTypes = map[string]bool{
 "image/jpeg": true,
 "image/png": true,
 "image/webp": true,
 "application/pdf": true,
 }
)

type uploadService struct {
 repo Repository
}

func NewService(repo Repository) Service {
 return &uploadService{repo: repo}
}

func (s *uploadService) UploadFile(ctx context.Context, bucket string, file *File) (string, error) {
 ctx, cancel := context.WithTimeout(ctx, uploadTimeout)// evita requisição "pendurada" em chamadas ao S3
 defer cancel()

 if err := s.validateBucketName(bucket); err != nil {
 return "", err
 }

 if err := s.validateFile(file); err != nil {
 slog.Error("security validation failed", "error", err, "filename", file.Name)
 return "", err
 }

 // UUID v7 mantém ordenação temporal e evita colisão/exposição de nomes originais.
 id, err := uuid.NewV7()
 if err != nil {
 slog.Error("uuid generation failed", "error", err)
 return "", fmt.Errorf("failed to generate unique id: %w", err)
 }

 file.Name = id.String() + filepath.Ext(file.Name)

 url, err := s.repo.Upload(ctx, bucket, file)
 if err != nil {
 slog.Error("repository upload failed", "error", err, "bucket", bucket)
 return "", err
 }

 file.URL = url
 slog.Info("file uploaded successfully", "url", url)
 return url, nil
}

func (s *uploadService) UploadMultipleFiles(ctx context.Context, bucket string, files []*File) ([]string, error) {
 // errgroup cancela o contexto se qualquer goroutine falhar.
 g, ctx := errgroup.WithContext(ctx)
 results := make([]string, len(files))

 for i, f := range files {
 i, f := i, f // evita captura incorreta das variáveis do loop
 g.Go(func() error {
 url, err := s.UploadFile(ctx, bucket, f)
 if err != nil {
 return err
 }
 results[i] = url
 return nil
 })
 }

 if err := g.Wait(); err != nil {
 return nil, err
 }

 return results, nil
}

func (s *uploadService) GetDownloadURL(ctx context.Context, bucket, key string) (string, error) {
 if err := s.validateBucketName(bucket); err != nil {
 return "", err
 }

 // Presign é a forma recomendada para acesso temporário a buckets privados.
 return s.repo.GetPresignURL(ctx, bucket, key, 15*time.Minute)
}

func (s *uploadService) DownloadFile(ctx context.Context, bucket, key string) (io.ReadCloser, error) {
 if err := s.validateBucketName(bucket); err != nil {
 return nil, err
 }
 return s.repo.Download(ctx, bucket, key)
}

func (s *uploadService) ListFiles(ctx context.Context, bucket, ext, token string, limit int) (*PaginatedFiles, error) {
 if err := s.validateBucketName(bucket); err != nil {
 return nil, err
 }

 if limit <= 0 {
 limit = 10
 }

 res, err := s.repo.List(ctx, bucket, "", token, int32(limit))
 if err != nil {
 return nil, err
 }

 if ext == "" {
 return res, nil
 }

 var filtered []FileSummary
 target := strings.ToLower(ext)

 if !strings.HasPrefix(target, ".") {
 target = "." + target
 }

 for _, f := range res.Files {
 if strings.ToLower(f.Extension) == target {
 filtered = append(filtered, f)
 }
 }

 res.Files = filtered
 return res, nil
}

func (s *uploadService) DeleteFile(ctx context.Context, bucket string, key string) error {
 ctx, cancel := context.WithTimeout(ctx, deleteTimeout)
 defer cancel()

 if key == "" {
 return fmt.Errorf("file key is required")
 }

 if err := s.validateBucketName(bucket); err != nil {
 return err
 }

 return s.repo.Delete(ctx, bucket, key)
}

func (s *uploadService) GetBucketStats(ctx context.Context, bucket string) (*BucketStats, error) {
 if err := s.validateBucketName(bucket); err != nil {
 return nil, err
 }
 return s.repo.GetStats(ctx, bucket)
}

func (s *uploadService) CreateBucket(ctx context.Context, bucket string) error {

 if err := s.validateBucketName(bucket); err != nil {
 return err
 }

 exists, err := s.repo.CheckBucketExists(ctx, bucket)
 if err != nil {
 return err
 }
 if exists {
 return ErrBucketAlreadyExists
 }

 return s.repo.CreateBucket(ctx, bucket)
}

func (s *uploadService) DeleteBucket(ctx context.Context, bucket string) error {
 if err := s.validateBucketName(bucket); err != nil {
 return err
 }
 return s.repo.DeleteBucket(ctx, bucket)
}

func (s *uploadService) EmptyBucket(ctx context.Context, bucket string) error {
 if err := s.validateBucketName(bucket); err != nil {
 return err
 }
 return s.repo.DeleteAll(ctx, bucket)
}

func (s *uploadService) ListAllBuckets(ctx context.Context) ([]BucketSummary, error) {
 return s.repo.ListBuckets(ctx)
}

func (s *uploadService) validateBucketName(bucket string) error {
 bucket = strings.TrimSpace(strings.ToLower(bucket))
 if bucket == "" {
 return ErrBucketNameRequired
 }

 if len(bucket) < minBucketNameLength || len(bucket) > maxBucketNameLength {
 return fmt.Errorf("bucket name length must be between %d and %d", minBucketNameLength, maxBucketNameLength)
 }

 if !bucketDNSNameRegex.MatchString(bucket) {
 return fmt.Errorf("invalid bucket name pattern")
 }

 if strings.Contains(bucket, "..") {
 return fmt.Errorf("bucket name cannot contain consecutive dots")
 }

 return nil
}

func (s *uploadService) validateFile(f *File) error {
 seeker, ok := f.Content.(io.Seeker)
 if !ok {
 return fmt.Errorf("file content must support seeking")
 }

 buffer := make([]byte, 512)
 n, err := f.Content.Read(buffer)
 if err != nil && err != io.EOF {
 return fmt.Errorf("failed to read file header: %w", err)
 }

 // Reposiciona o stream para o início antes do upload.
 if _, err := seeker.Seek(0, io.SeekStart); err != nil {
 return fmt.Errorf("failed to reset file pointer: %w", err)
 }

 detectedType := http.DetectContentType(buffer[:n])
 if !allowedTypes[detectedType] {
 slog.Warn("rejected file type", "type", detectedType)
 return ErrInvalidFileType
 }

 return nil
}

Destaques técnicos no Serviço

Concorrência com errgroup

No upload múltiplo, eu não subo arquivo por arquivo. Eu disparo uploads em paralelo e deixo o errgroup gerenciar cancelamento: se um upload falhar, os demais são sinalizados para parar. Na prática, o tempo total tende a ser próximo do upload mais lento, e não a soma de todos.

Segurança: validação de tipo de arquivo

A validação lê um trecho do conteúdo para identificar o tipo real do arquivo, reduzindo risco de arquivos maliciosos com extensão “fingida”.

Resiliência: timeouts por operação

Operações como upload e delete têm características diferentes; por isso, faz sentido ter tempos limites distintos para manter a API responsiva e evitar recursos travados.

Encapsulamento e injeção de dependência

O Service depende de um Repository. Isso torna o código altamente testável: em testes, eu simulo o repositório com mocks sem precisar de AWS.

Camada de Handler

O Handler traduz HTTP para o mundo da aplicação: extrai parâmetros, valida o mínimo, chama o Service e retorna JSON (ou streaming no caso de download).

Eu utilizei o Gin pela combinação de performance, simplicidade e ecossistema de middlewares.

package upload

import (
 "errors"
 "io"
 "net/http"
 "strconv"

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

type Handler struct {
 service Service
}

func NewHandler(s Service) *Handler {
 return &Handler{service: s}
}

func (h *Handler) UploadFile(c *gin.Context) {
 bucket := c.PostForm("bucket")
 fileHeader, err := c.FormFile("file")
 if err != nil {
 c.JSON(http.StatusBadRequest, gin.H{"error": "file field is required"})
 return
 }

 openedFile, err := fileHeader.Open()
 if err != nil {
 c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to open file"})
 return
 }
 defer openedFile.Close()// garante que o stream do multipart seja fechado

 file := &File{
 Name: fileHeader.Filename,
 Content: openedFile,// stream: evita carregar o arquivo inteiro em memória
 Size: fileHeader.Size,
 ContentType: fileHeader.Header.Get("Content-Type"),
 }

 url, err := h.service.UploadFile(c.Request.Context(), bucket, file)
 if err != nil {
 h.handleError(c, err)
 return
 }

 c.JSON(http.StatusCreated, gin.H{"url": url})
}

func (h *Handler) UploadMultiple(c *gin.Context) {
 bucket := c.PostForm("bucket")
 form, err := c.MultipartForm()
 if err != nil {
 c.JSON(http.StatusBadRequest, gin.H{"error": "invalid multipart form"})
 return
 }

 filesHeaders := form.File["files"]
 if len(filesHeaders) == 0 {
 c.JSON(http.StatusBadRequest, gin.H{"error": "no files provided"})
 return
 }

 var filesToUpload []*File
 for _, header := range filesHeaders {
 openedFile, err := header.Open()
 if err != nil {
 continue
 }

 filesToUpload = append(filesToUpload, &File{
 Name: header.Filename,
 Content: openedFile,
 Size: header.Size,
 ContentType: header.Header.Get("Content-Type"),
 })
 }

 // Fecha todos os streams abertos (mesmo em caso de erro no Service).
 defer func() {
 for _, f := range filesToUpload {
 f.Content.Close()
 }
 }()

 urls, err := h.service.UploadMultipleFiles(c.Request.Context(), bucket, filesToUpload)
 if err != nil {
 h.handleError(c, err)
 return
 }

 c.JSON(http.StatusCreated, gin.H{"urls": urls})
}

func (h *Handler) GetPresignedURL(c *gin.Context) {
 bucket := c.Query("bucket")
 key := c.Query("key")

 url, err := h.service.GetDownloadURL(c.Request.Context(), bucket, key)
 if err != nil {
 h.handleError(c, err)
 return
 }

 c.JSON(http.StatusOK, gin.H{"presigned_url": url})
}

func (h *Handler) DownloadFile(c *gin.Context) {
 bucket := c.Query("bucket")
 key := c.Query("key")

 stream, err := h.service.DownloadFile(c.Request.Context(), bucket, key)
 if err != nil {
 h.handleError(c, err)
 return
 }
 defer stream.Close()

 // Streaming: os bytes fluem do S3 para o cliente sem serem carregados em RAM pela API.
 c.Header("Content-Disposition", "attachment; filename="+key)
 c.Header("Content-Type", "application/octet-stream")

 _, _ = io.Copy(c.Writer, stream)
}

func (h *Handler) ListFiles(c *gin.Context) {
 limit, _ := strconv.Atoi(c.DefaultQuery("limit", "10"))

 result, err := h.service.ListFiles(
 c.Request.Context(),
 c.Query("bucket"),
 c.Query("extension"),
 c.Query("token"),
 limit,
 )

 if err != nil {
 h.handleError(c, err)
 return
 }

 c.JSON(http.StatusOK, result)
}

func (h *Handler) DeleteFile(c *gin.Context) {
 err := h.service.DeleteFile(c.Request.Context(), c.Query("bucket"), c.Query("key"))
 if err != nil {
 h.handleError(c, err)
 return
 }

 c.Status(http.StatusNoContent)
}

func (h *Handler) GetBucketStats(c *gin.Context) {
 bucket := c.Query("bucket")
 if bucket == "" {
 c.JSON(http.StatusBadRequest, gin.H{"error": "bucket parameter is required"})
 return
 }

 stats, err := h.service.GetBucketStats(c.Request.Context(), bucket)
 if err != nil {
 c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 return
 }

 c.JSON(http.StatusOK, stats)
}

func (h *Handler) CreateBucket(c *gin.Context) {
 var body struct {
 Name string `json:"bucket_name" binding:"required"`
 }

 if err := c.ShouldBindJSON(&body); err != nil {
 c.JSON(http.StatusBadRequest, gin.H{"error": "valid bucket_name is required"})
 return
 }

 if err := h.service.CreateBucket(c.Request.Context(), body.Name); err != nil {
 h.handleError(c, err)
 return
 }

 c.Status(http.StatusCreated)
}

func (h *Handler) ListBuckets(c *gin.Context) {
 buckets, err := h.service.ListAllBuckets(c.Request.Context())
 if err != nil {
 h.handleError(c, err)
 return
 }
 c.JSON(http.StatusOK, buckets)
}

func (h *Handler) DeleteBucket(c *gin.Context) {
 if err := h.service.DeleteBucket(c.Request.Context(), c.Query("name")); err != nil {
 h.handleError(c, err)
 return
 }
 c.Status(http.StatusNoContent)
}

func (h *Handler) EmptyBucket(c *gin.Context) {
 bucket := c.Query("bucket")
 if bucket == "" {
 c.JSON(http.StatusBadRequest, gin.H{"error": "bucket parameter is required"})
 return
 }

 err := h.service.EmptyBucket(c.Request.Context(), bucket)
 if err != nil {
 c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 return
 }

 c.Status(http.StatusNoContent)
}

func (h *Handler) handleError(c *gin.Context, err error) {
 // Mapeia erros semânticos (domínio) para status HTTP.
 switch {
 case errors.Is(err, ErrInvalidFileType),
 errors.Is(err, ErrBucketNameRequired):
 c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})

 case errors.Is(err, ErrBucketAlreadyExists):
 c.JSON(http.StatusConflict, gin.H{"error": err.Error()})

 case errors.Is(err, ErrFileNotFound):
 c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})

 case errors.Is(err, ErrOperationTimeout):
 c.JSON(http.StatusGatewayTimeout, gin.H{"error": "request timed out"})

 default:
 c.JSON(http.StatusInternalServerError, gin.H{"error": "an unexpected error occurred"})
 }
}

Decisões técnicas no handler

Multipart/form-data sem “estourar RAM”: eu abro o arquivo como stream, evitando carregar tudo em memória.
Streaming de download: crio um “cano” entre o S3 e o cliente. Isso permite suportar arquivos maiores com hardware modesto.
Tratamento centralizado de erros: em vez de espalhar if err != nil por todas as rotas, o Handler mapeia erros semânticos do domínio para códigos HTTP consistentes (400, 404, 409, 504 etc.).

O ponto de entrada (main)

O main carrega configurações, instancia dependências e sobe o servidor. Aqui entra um dos conceitos mais úteis para manter projetos saudáveis: injeção de dependência.

Em termos práticos: o main cria o cliente AWS → passa para o repositório → passa para o service → passa para o handler. Isso deixa o sistema modular e fácil de testar.

package main

import (
 "context"
 "log/slog"
 "os"
 "time"

 // Internal packages
 appConfig "github.com/JoaoOliveira889/s3-api/internal/config"
 "github.com/JoaoOliveira889/s3-api/internal/middleware"
 "github.com/JoaoOliveira889/s3-api/internal/upload"
 "github.com/gin-gonic/gin"

 // External packages
 configAWS "github.com/aws/aws-sdk-go-v2/config"
 "github.com/aws/aws-sdk-go-v2/service/s3"
 "github.com/joho/godotenv"
)

func main() {
 _ = godotenv.Load()// .env é útil em dev; em produção, prefira variáveis do ambiente/IAM Roles

 cfg := appConfig.Load()

 // Logs em JSON facilitam busca/indexação em ferramentas como CloudWatch/ELK/Loki.
 logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
 slog.SetDefault(logger)

 r := gin.New()

 // Middlewares globais: aplicados a todas as rotas.
 r.Use(middleware.RequestTimeoutMiddleware(cfg.UploadTimeout))
 r.Use(middleware.LoggingMiddleware())
 r.Use(gin.Recovery())// evita que um panic derrube o servidor inteiro

 ctx := context.Background()
 awsCfg, err := configAWS.LoadDefaultConfig(ctx, configAWS.WithRegion(cfg.AWSRegion))
 if err != nil {
 slog.Error("failed to load AWS SDK config", "error", err)
 os.Exit(1)
 }

 // Injeção de dependência (bootstrap): client -> repo -> service -> handler.
 s3Client := s3.NewFromConfig(awsCfg)
 repo := upload.NewS3Repository(s3Client, cfg.AWSRegion)
 service := upload.NewService(repo)
 handler := upload.NewHandler(service)

 api := r.Group("/api/v1")
 {
 api.GET("/health", func(c *gin.Context) {
 c.JSON(200, gin.H{
 "status": "healthy",
 "env": cfg.Env,
 "timestamp": time.Now().Format(time.RFC3339),
 })
 })

 api.GET("/list", handler.ListFiles)
 api.POST("/upload", handler.UploadFile)
 api.POST("/upload-multiple", handler.UploadMultiple)
 api.GET("/download", handler.DownloadFile)
 api.GET("/presign", handler.GetPresignedURL)
 api.DELETE("/delete", handler.DeleteFile)

 buckets := api.Group("/buckets")
 {
 buckets.POST("/create", handler.CreateBucket)
 buckets.DELETE("/delete", handler.DeleteBucket)
 buckets.GET("/stats", handler.GetBucketStats)
 buckets.GET("/list", handler.ListBuckets)
 buckets.DELETE("/empty", handler.EmptyBucket)
 }
 }

 slog.Info("server successfully started",
 "port", cfg.Port,
 "env", cfg.Env,
 "region", cfg.AWSRegion,
 )

 if err := r.Run(":" + cfg.Port); err != nil {
 slog.Error("server failed to shut down properly", "error", err)
 os.Exit(1)
 }
}

Destaques técnicos na `main`

Logging estruturado: logs em JSON são mais úteis para indexação e busca em ferramentas como CloudWatch, ELK ou Datadog.
Middlewares em cadeia: aplico log e timeout globalmente, garantindo consistência em todas as rotas.
Recovery: evita que um panic derrube a API inteira.
Agrupamento e versionamento: /api/v1 facilita evolução sem quebrar clientes antigos.

Segurança e configuração: gerenciando credenciais

Para a API falar com a AWS, ela precisa de credenciais. Mas expor chaves no código é um risco sério. Por isso, em desenvolvimento local eu uso variáveis de ambiente (via .env) e, em produção, a evolução natural é usar IAM Roles.

Arquivo `.env` (desenvolvimento local)

Na raiz do projeto, criamos o arquivo .env. Ele servirá para armazenar configurações de servidor e as chaves secretas da AWS.

Atenção: Este arquivo deve estar obrigatoriamente no seu .gitignore. Nunca envie suas chaves para o GitHub ou qualquer outro sistema de controle de versão.

# Server Settings
PORT=8080
APP_ENV=development

# AWS Configuration
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=SUA_ACCESS_KEY_AQUI
AWS_SECRET_ACCESS_KEY=SUA_SECRET_KEY_AQUI

# Application Settings
UPLOAD_TIMEOUT_SECONDS=60

Obtendo Credenciais no Console AWS (IAM)

As chaves (Access Keys) são geradas no IAM. Para estudos você pode usar permissões amplas, mas o ideal é seguir o princípio do menor privilégio e restringir ao bucket e ações necessárias.

Passo a Passo:

Acesse o IAM: No console da AWS, busque por “IAM”.
Crie um Usuário: Vá em Users > Create user.
Configuração: Defina um nome (ex: s3-api-manager). Não é necessário habilitar o acesso ao Console Visual (AWS Management Console) para este usuário, pois ele será usado apenas via código.
Permissões (Princípio do Menor Privilégio): Escolha Attach policies directly.
- Nota: Para fins de estudo, você pode selecionar AmazonS3FullAccess. Em um cenário de produção real, o ideal é criar uma política personalizada que dê acesso apenas ao bucket específico que você irá usar.
Gerar as Chaves: Após criar o usuário, clique no nome dele, vá na aba Security credentials e procure pela seção Access keys.
Criação: Clique em Create access key, selecione a opção “Local code” e avance.

IMPORTANTE: Você verá a Access Key ID e a Secret Access Key. Copie e cole no seu .env agora, pois a Secret Key nunca mais será exibida.

Middlewares: observabilidade e resiliência

Middlewares são o lugar certo para comportamentos globais: logs, timeouts, correlação e proteção. Em vez de replicar isso por endpoint, eu centralizo.

Logging estruturado

O log é escrito após a requisição terminar. Isso permite registrar status code e latência com precisão, facilitando análise de performance e erros.

package middleware

import (
 "log/slog"
 "time"

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

func LoggingMiddleware() gin.HandlerFunc {
 return func(c *gin.Context) {
 start := time.Now()
 path := c.Request.URL.Path
 raw := c.Request.URL.RawQuery

 c.Next()// executa o handler antes de logar, permitindo capturar status e latência reais

 if raw != "" {
 path = path + "?" + raw
 }

 slog.Info("incoming request",
 "method", c.Request.Method,
 "path", path,
 "status", c.Writer.Status(),
 "latency", time.Since(start).String(),
 "ip", c.ClientIP(),
 "user_agent", c.Request.UserAgent(),
 )
 }
}

Controle de timeout

Em sistemas que dependem de serviços externos, é perigoso deixar conexões abertas indefinidamente. O middleware de timeout cancela a requisição quando ela excede um limite, liberando recursos.

package middleware

import (
 "context"
 "net/http"
 "time"

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

func RequestTimeoutMiddleware(timeout time.Duration) gin.HandlerFunc {
 return func(c *gin.Context) {
 // Propaga um contexto com deadline para toda a cadeia (handlers + chamadas ao S3).
 ctx, cancel := context.WithTimeout(c.Request.Context(), timeout)
 defer cancel()

 c.Request = c.Request.WithContext(ctx)

 finished := make(chan struct{}, 1)

 go func() {
 c.Next()
 finished <- struct{}{}
 }()

 select {
 case <-finished:
 return
 case <-ctx.Done():
 // Se estourar o deadline, aborta a request e devolve 504.
 if ctx.Err() == context.DeadlineExceeded {
 c.AbortWithStatusJSON(http.StatusGatewayTimeout, gin.H{
 "error": "request timed out",
 })
 }
 }
 }
}

Destaques técnicos Middlewares

c.Next() no momento certo: garante que o log capture status e latência reais.
select e canais: padrão claro para observar “terminou vs expirou”, mantendo o controle do ciclo de vida da requisição.
Logs estruturados: tornam mais fácil construir dashboards e alarmes.

Testes Unitários

Um dos maiores benefícios dessa arquitetura é a capacidade de testar a lógica de negócio isoladamente, sem AWS e sem internet.

Eu uso mocks para simular o repositório e foco em validar: regras de bucket, validações de tipo de arquivo, geração de identificadores e tratamento de erros.

package upload

import (
 "context"
 "io"
 "time"

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

type RepositoryMock struct {
 mock.Mock
}

func (m *RepositoryMock) Delete(ctx context.Context, bucket string, key string) error {
 panic("unimplemented")
}

func (m *RepositoryMock) DeleteAll(ctx context.Context, bucket string) error {
 panic("unimplemented")
}

func (m *RepositoryMock) DeleteBucket(ctx context.Context, bucket string) error {
 panic("unimplemented")
}

func (m *RepositoryMock) GetStats(ctx context.Context, bucket string) (*BucketStats, error) {
 panic("unimplemented")
}

func (m *RepositoryMock) ListBuckets(ctx context.Context) ([]BucketSummary, error) {
 panic("unimplemented")
}

func (m *RepositoryMock) Upload(ctx context.Context, bucket string, file *File) (string, error) {
 args := m.Called(ctx, bucket, file)
 return args.String(0), args.Error(1)
}

func (m *RepositoryMock) Download(ctx context.Context, bucket, key string) (io.ReadCloser, error) {
 args := m.Called(ctx, bucket, key)
 if args.Get(0) == nil {
 return nil, args.Error(1)
 }
 return args.Get(0).(io.ReadCloser), args.Error(1)
}

func (m *RepositoryMock) GetPresignURL(ctx context.Context, bucket, key string, expiration time.Duration) (string, error) {
 args := m.Called(ctx, bucket, key, expiration)
 return args.String(0), args.Error(1)
}

func (m *RepositoryMock) List(ctx context.Context, bucket, prefix, token string, limit int32) (*PaginatedFiles, error) {
 args := m.Called(ctx, bucket, prefix, token, limit)
 return args.Get(0).(*PaginatedFiles), args.Error(1)
}

func (m *RepositoryMock) CheckBucketExists(ctx context.Context, bucket string) (bool, error) {
 args := m.Called(ctx, bucket)
 return args.Bool(0), args.Error(1)
}

func (m *RepositoryMock) CreateBucket(ctx context.Context, bucket string) error {
 args := m.Called(ctx, bucket)
 return args.Error(0)
}

Implementando os Testes do Serviço

No arquivo service_test.go, focamos em testar as regras de negócio: validação de nomes de bucket, geração de UUID e tratamento de erros.

package upload

import (
 "context"
 "strings"
 "testing"
 "time"

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

type readSeekCloser struct {
 *strings.Reader
}

func (rsc readSeekCloser) Close() error { return nil }

func TestUploadFile_InvalidBucket(t *testing.T) {
 mockRepo := new(RepositoryMock)
 service := NewService(mockRepo)

 result, err := service.UploadFile(context.Background(), "", &File{})

 assert.Error(t, err)

 assert.Empty(t, result)

 assert.ErrorIs(t, err, ErrBucketNameRequired)
}

func TestUploadFile_Success(t *testing.T) {
 mockRepo := new(RepositoryMock)
 service := NewService(mockRepo)
 ctx := context.Background()

 content := strings.NewReader("\x89PNG\r\n\x1a\n" + strings.Repeat("0", 512))
 file := &File{
 Name: "test-image.png",
 Content: readSeekCloser{content},
 }

 bucket := "my-test-bucket"
 expectedURL := "https://s3.amazonaws.com/my-test-bucket/unique-id.png"

 mockRepo.On("Upload", mock.Anything, bucket, mock.AnythingOfType("*upload.File")).Return(expectedURL, nil)

 resultURL, err := service.UploadFile(ctx, bucket, file)

 assert.NoError(t, err)
 assert.NotEmpty(t, resultURL)
 assert.Equal(t, expectedURL, resultURL)

 mockRepo.AssertExpectations(t)
}

func TestGetDownloadURL_Success(t *testing.T) {
 mockRepo := new(RepositoryMock)
 service := NewService(mockRepo)

 bucket := "my-bucket"
 key := "image.png"
 expectedPresignedURL := "https://s3.amazonaws.com/my-bucket/image.png?signed=true"

 mockRepo.On("GetPresignURL", mock.Anything, bucket, key, 15*time.Minute).
 Return(expectedPresignedURL, nil)

 url, err := service.GetDownloadURL(context.Background(), bucket, key)

 assert.NoError(t, err)
 assert.Equal(t, expectedPresignedURL, url)
 mockRepo.AssertExpectations(t)
}

Destaques técnicos nos testes

Testar regra, não integração: o Service precisa ser previsível; integrações ficam para testes específicos.
Validação de segurança refletida nos testes: se a API valida MIME, os testes precisam respeitar isso para serem realistas.
errors.Is e erros semânticos: isso fortalece consistência e facilita assertivas.

Automação com GitHub Actions

A cada push/PR, o CI instala dependências e roda testes. Isso mantém a branch principal estável e reduz o risco de regressão.

Configurando o Workflow (go.yml)

O arquivo de configuração deve ser criado em .github/workflows/go.yml. Ele define os passos necessários para validar a saúde do projeto.

# .github/workflows/go.yml
name: Go CI

on:
 push:
 branches: [ main, develop ]
 pull_request:
 branches: [ main ]

jobs:
 test:
 name: Run Tests 
 runs-on: ubuntu-latest

 steps:
 - name: Checkout code
 uses: actions/checkout@v4

 - name: Set up Go
 uses: actions/setup-go@v5
 with:
 go-version: '1.25.5'
 cache: true

 - name: Install dependencies
 run: go mod download

 - name: Verify dependencies
 run: go mod verify

 - name: Run tests
 run: go test -v -race ./...

Destaques técnicos na Automação

Race detector (-race): importante porque há concorrência (uploads paralelos).
Cache de dependências: acelera builds e economiza tempo de execução.
Pipeline seguro: como o Service é testado com mocks, o CI não precisa de credenciais AWS.

Configurações Centralizadas

Em projetos pequenos, é comum espalhar os.Getenv. Em projetos que crescem, isso vira dívida técnica: dependências ficam implícitas e difíceis de rastrear.

Centralizar config cria uma “fonte única da verdade”: validação e tipagem no início da execução e consumo simples no restante do código.

package config

import (
 "os"
 "strconv"
 "time"
)

type Config struct {
 Port string
 AWSRegion string
 UploadTimeout time.Duration
 Env string
}

func Load() *Config {
 return &Config{
 Port: getEnv("PORT", "8080"),
 AWSRegion: getEnv("AWS_REGION", "us-east-1"),

 // Converte o valor uma única vez para time.Duration,
 // evitando cálculos repetidos no restante da aplicação.
 UploadTimeout: time.Duration(getEnvAsInt("UPLOAD_TIMEOUT_SECONDS", 30)) * time.Second,
 Env: getEnv("APP_ENV", "development"),
 }
}

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

func getEnvAsInt(key string, defaultValue int) int {
 valueStr := getEnv(key, "")
 if value, err := strconv.Atoi(valueStr); err == nil {
 return value
 }
 return defaultValue
}

Erros Semânticos

O Service não deve retornar códigos HTTP. Ele deve retornar erros que façam sentido no domínio, e o Handler decide o status adequado. Isso mantém o domínio reutilizável (HTTP hoje, gRPC amanhã, CLI depois).

package upload

import "errors"

var (
 ErrBucketNameRequired = errors.New("bucket name is required")
 ErrFileNotFound = errors.New("file not found in storage")
 ErrInvalidFileType = errors.New("file type not allowed or malicious content detected")
 ErrBucketAlreadyExists = errors.New("bucket already exists")
 ErrOperationTimeout = errors.New("the operation timed out")
)

Destaques técnicos nos Erros

Domínio agnóstico: erros continuam fazendo sentido fora do HTTP.
Comparação robusta com errors.Is: mais seguro do que comparar strings.
Consistência: mensagens estáveis e previsíveis para quem consome a API.

Containerização com Docker

Containerizar garante que a API rode da mesma forma em qualquer ambiente. Aqui eu uso multi-stage build: compilo em uma imagem com toolchain e rodo em uma imagem final menor e mais segura.

Dockerfile otimizado

services:
 s3-api:
 build: .
 ports:
 - "8080:8080"
 env_file:
 - .env
 restart: always

Orquestração com Docker Compose

O docker-compose.yml simplifica a inicialização da aplicação, gerenciando as portas e carregando automaticamente o nosso arquivo de segredos (.env).

# Stage 1: Build the Go binary
FROM golang:1.25.5-alpine AS builder

WORKDIR /app

# Copy dependency files
COPY go.mod go.sum ./
RUN go mod download

# Copy the source code
COPY . .

# Build the application with optimizations
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-w -s" -o main ./cmd/api/main.go

# Stage 2: Create the final lightweight image
FROM alpine:latest

RUN apk --no-cache add ca-certificates

WORKDIR /root/

# Copy the binary from the builder stage
COPY --from=builder /app/main .
# Copy the .env file (optional, better to use environment variables in prod)
COPY --from=builder /app/.env . 

EXPOSE 8080

CMD ["./main"]

Destaques técnicos Docker

Certificados SSL: imagens mínimas nem sempre vêm com CA certs; sem isso, chamadas HTTPS podem falhar.
Binário enxuto: flags de build reduzem tamanho e aceleram deploy.
Cache inteligente: copiar go.mod/go.sum antes do código ajuda o Docker a reaproveitar layers.

Comandos Úteis

Testes

go test ./...

Executar o projeto

go run cmd/api/main.go

Gestão do Container

# Construir a imagem e subir o container em background
docker-compose up --build -d

# Visualizar logs da aplicação em tempo real
docker logs -f go-s3-api

# Derrubar o container
docker-compose down

Conclusão

Construir esta API de gerenciamento para o Amazon S3 foi uma forma prática de unir uma necessidade real (automatizar meu workflow do blog) com aprendizado sólido (Go, AWS, segurança, observabilidade e arquitetura).

Links do projeto

Repositório Principal no GitHub: Este é o repositório “vivo”, que pode evoluir e ficar diferente do que está descrito neste artigo.
Código Versão do Artigo: Para ver o projeto exatamente como foi construído e explicado aqui, com estado estático.

Referências

Go Standard Project Layout: https://github.com/golang-standards/project-layout
Clean Architecture (The Clean Code Blog): https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html
WS SDK for Go v2 - S3 Developer Guide: https://aws.github.io/aws-sdk-go-v2/docs/getting-started/
Go Concurrency Patterns (Context Package): https://go.dev/blog/context
Gin Web Framework: https://gin-gonic.com/docs/
Testify - Testing Toolkit: https://github.com/stretchr/testify
Google UUID Package (v7 support): https://github.com/google/uuid
Errgroup Package (Concorrência): https://pkg.go.dev/golang.org/x/sync/errgroup
Dockerizing a Go App: https://docs.docker.com/language/golang/build-images/
GitHub Actions for Go: https://github.com/actions/setup-go

Redis Implementando Pub/Sub e Streams em .NET 10

Fri, 09 Jan 2026 00:00:00 +0000

Redis (Remote Dictionary Server) pode fazer muito mais do que apenas atuar como um cache. Eu sei que esse é o caso de uso mais comum, já que ele protege o banco de dados contra requisições excessivas e melhora o tempo de resposta ao manter os dados em memória, mas o Redis oferece muito mais do que isso.

O Redis também pode funcionar como um poderoso message broker. Com suporte nativo a Pub/Sub e Streams, se você já possui uma instância do Redis em execução, pode valer a pena explorar esses outros recursos para atender melhor às necessidades da sua aplicação.

Neste artigo, vou demonstrar como implementar tanto Pub/Sub quanto Streams como message brokers utilizando Redis e .NET. Ao final, você será capaz de avaliar qual abordagem é a melhor opção para o seu cenário específico.

Conceitos: Pub/Sub vs Streams

Pense no Pub/Sub como uma transmissão de rádio ao vivo. Se o seu rádio estiver desligado, você perde a música. Streams, por outro lado, são mais parecidos com o YouTube. Você pode assistir ao vídeo quando quiser, e ele permanece disponível até ser deletado. Abaixo está uma comparação entre os dois.

Recurso	Pub/Sub	Streams
Persistência	Não. As mensagens são perdidas se ninguém estiver ouvindo	Sim. As mensagens são armazenadas no Redis até serem deletadas
Entrega	Um-para-muitos	Muitos-para-muitos
Histórico	Não	Sim. É possível ler mensagens “antigas”
Caso de uso	Chats em tempo real, notificações	Processamento de pedidos, logs de auditoria, event sourcing

Configuração do Ambiente

Vamos construir este projeto com .NET 10. Primeiro, crie um projeto de Minimal API a partir do terminal:

# 1. Create project folder
mkdir RedisMessageLab && cd RedisMessageLab

# 2. Create Minimal API project
dotnet new webapi -n MessagingApi -minimal

# 3. Add the Redis Driver
cd MessagingApi
dotnet add package StackExchange.Redis

# 4. Create the Docker Compose file in the root
cd ..
touch docker-compose.yml

Configuração do Docker

Crie um arquivo docker-compose.yml e adicione a seguinte configuração:

services:
 redis:
 image: redis:7.4-alpine
 container_name: redis-lab
 ports:
 - "6379:6379"
 command: ["redis-server", "--appendonly", "yes"] # Enable persistence for Streams

Inicie o container com:

docker-compose up -d

Implementação do Projeto

Model

Crie um record AppMessage para transportar dados pelo nosso sistema.

public record AppMessage(string Id, string Content, string Sender);

Interface

Crie uma interface IRedisService.

public interface IRedisService
{
 Task<long> PublishAsync(AppMessage message);
 Task AppendAsync(AppMessage message);
 Task<AppMessage?> ConsumeAndStackDeleteAsync();
 Task<List<AppMessage>> PeekHistoryAsync();
}

Service

Crie a RedisService class.

public class RedisService(IConnectionMultiplexer redis) : IRedisService
{
 private const string Channel = "live_updates";
 private const string Stream = "audit_stream";

 public async Task<long> PublishAsync(AppMessage message)
 {
 var sub = redis.GetSubscriber();
 string json = JsonSerializer.Serialize(message);

 // Publish returns the count of active subscribers
 long subscribersCount = await sub.PublishAsync(RedisChannel.Literal(Channel), json);

 if (subscribersCount != 0) return subscribersCount;

 // This will show up in your .NET Terminal/Console
 Console.ForegroundColor = ConsoleColor.Yellow;
 Console.WriteLine($"[PUB/SUB WARNING] Message {message.Id} was sent, but 0 subscribers were listening. Data is lost!");
 Console.ResetColor();

 return subscribersCount;
 }

 public async Task AppendAsync(AppMessage message)
 {
 var db = redis.GetDatabase();
 await db.StreamAddAsync(Stream, [
 new NameValueEntry("id", message.Id),
 new NameValueEntry("content", message.Content)]);
 }

 public async Task<AppMessage?> ConsumeAndStackDeleteAsync()
 {
 var db = redis.GetDatabase();
 // Read the oldest message
 var messages = await db.StreamReadAsync(Stream, "0-0", count: 1);
 if (messages.Length == 0) return null;

 var msg = messages.First();
 var note = new AppMessage(msg.Values[0].Value!, msg.Values[1].Value!, "Stream");

 // ANSWERING YOUR DOUBT: Delete after consuming
 await db.StreamDeleteAsync(Stream, [msg.Id]);
 return note;
 }

 public async Task<List<AppMessage>> PeekHistoryAsync()
 {
 var db = redis.GetDatabase();

 // XRANGE audit_stream - + (Read everything from start to finish)
 var entries = await db.StreamRangeAsync(Stream, "-", "+");

 return entries.Select(e => new AppMessage(
 e.Values.FirstOrDefault(v => v.Name == "id").Value!,
 e.Values.FirstOrDefault(v => v.Name == "content").Value!,
 "Stream History"
 )).ToList();
 }
}

Workers

Crie um worker LiveNotificationWorker para lidar com notificações em tempo real.

public class LiveNotificationWorker : BackgroundService
{
 protected override async Task ExecuteAsync(CancellationToken stoppingToken) {
 var redis = await ConnectionMultiplexer.ConnectAsync("localhost:6379");
 var sub = redis.GetSubscriber();

 await sub.SubscribeAsync(RedisChannel.Literal("live_updates"), (channel, message) => {
 // This proves Pub/Sub success in the logs
 Console.WriteLine($"[PUB/SUB SUCCESS] Received Live: {message}");
 });
 }
}

Program.cs

Abra o Program.cs e adicione o código abaixo.

var builder = WebApplication.CreateBuilder(args);
var multiplexer = ConnectionMultiplexer.Connect("localhost:6379");
builder.Services.AddSingleton<IConnectionMultiplexer>(multiplexer);
builder.Services.AddScoped<IRedisService, RedisService>();
builder.Services.AddHostedService<LiveNotificationWorker>();

var app = builder.Build();

// Endpoint 1: Test Pub/Sub
app.MapPost("/broadcast", async (AppMessage message, IRedisService service) => {
 long listeners = await service.PublishAsync(message);
 return Results.Ok(new {
 Mechanism = "Pub/Sub",
 ActiveListeners = listeners,
 Status = listeners > 0 ? "Delivered" : "Lost (No Listeners)"
 });
});

// Endpoint 2: Test Stream Storage
app.MapPost("/log", async (AppMessage message, IRedisService service) => {
 await service.AppendAsync(message);
 return Results.Ok("Message logged in Stream.");
});

// Endpoint 3: Test Stream Consume & Delete
app.MapPost("/log/process", async (IRedisService service) => {
 var note = await service.ConsumeAndStackDeleteAsync();
 return note is null ? Results.NotFound("No logs left.") : Results.Ok(note);
});

// Endpoint 4: Peek at History (Without deleting)
app.MapGet("/log/history", async (IRedisService service) =>
{
 var history = await service.PeekHistoryAsync();
 return history.Count != 0 ? Results.Ok(history) : Results.NotFound("The Stream is empty.");
});

app.Run();

Comparação

Recurso	Sucesso com Pub/Sub	Sucesso com Streams
Entrega de dados	Instantânea, apenas para usuários ativos	Armazenada, pode ser processada depois
Limpeza	Automática (nada é armazenado)	Manual (você deve usar `XDEL` ou `XTRIM`)
Garantia	Nenhuma	Pelo menos uma vez (at-least-once)

Testando os endpoints

Vou usar o Apidog para testar os endpoints, mas você pode usar a ferramenta de sua preferência.

Execute o projeto a partir do terminal com:

dotnet run

O projeto deverá estar em execução em http://localhost:5040.

Pub/Sub Broadcast

Este endpoint envia uma mensagem que o worker em background deve receber instantaneamente no terminal.

Método: POST
Endpoint: /broadcast

Body (JSON)

{
 "id": "PS-100",
 "content": "Live alert: System update at 10 PM",
 "sender": "AdminPanel"
}

No Apidog, você verá a mensagem "Message broadcasted. Check terminal for success." e, no terminal, deverá ver a mensagem conforme mostrado na imagem abaixo.

Simular Pub/Sub sem Worker

Se você quiser simular um cenário em que nenhum worker está em execução, siga estes passos:

Comente esta linha no Program.cs: builder.Services.AddHostedService<LiveNotificationWorker>();
Envie uma requisição para /broadcast.
A API retorna 200 OK, mas a mensagem é perdida para sempre. Você não verá a mensagem de sucesso no terminal, como aconteceu no teste anterior.

Stream Log

Este endpoint envia uma mensagem para um Redis Stream, onde ela permanecerá até que você a processe manualmente.

Método: POST
Endpoint: /log

Body (JSON)

{
 "id": "STR-500",
 "content": "CRITICAL: Database connection retry",
 "sender": "DB-Monitor"
}

Se a mensagem for publicada com sucesso, você verá na resposta "Message logged in Stream."

Nota: Você pode enviar múltiplas mensagens; basta alterar algum campo no body para ilustrar melhor o teste.

Peek History on Stream

Com este endpoint, você pode recuperar todas as mensagens publicadas no Stream que ainda não foram consumidas.

Método: GET
Endpoint: /log/history
Body: Nenhum

Você verá todas as mensagens publicadas na resposta:

Stream Process

Esta requisição busca a mensagem mais antiga do stream e, em seguida, a remove do Redis.

Método: POST
Endpoint: /log/process
Body: Nenhum

Na primeira vez que você clicar em Send, receberá o JSON referente à mensagem STR-500.
Na segunda vez que você clicar em Send, se nenhuma mensagem adicional tiver sido enviada, você receberá uma resposta 404 Not Found (pois a mensagem foi removida após o primeiro consumo). Caso você envie mais mensagens para o endpoint /log, será necessário consumir todas elas antes de receber o 404, o que indica que o stream está vazio.

Para visualizar as mensagens armazenadas no terminal, você pode usar o seguinte comando:

docker exec -it redis-lab redis-cli XRANGE audit_stream - +

Fluxo do Processo

O diagrama ilustra a diferença fundamental entre Redis Pub/Sub e Redis Streams em termos de entrega e persistência de mensagens.

Conclusão

Como demonstrado ao longo deste artigo, o Redis é uma opção sólida para ser utilizado como message broker, especialmente quando o tempo de resposta é crítico para a sua aplicação ou quando você já possui uma instância do Redis em execução e não quer introduzir uma ferramenta adicional de mensageria.

Você pode escolher Pub/Sub quando precisar construir funcionalidades como um chat em tempo real, um lobby de jogos ou um sistema de matching por proximidade. Se a sua aplicação exige monitoramento de usuários ativos ou atualizações em tempo real, e a perda ocasional de mensagens é aceitável, o Pub/Sub é uma boa escolha. Ele é rápido, leve e não consome memória armazenando mensagens.

Por outro lado, quando a retenção de mensagens é crítica e você não pode se dar ao luxo de perder dados — como em fluxos de pagamento ou processamento de pedidos — Streams são a melhor opção. As mensagens são persistidas, ordenadas e podem ser processadas posteriormente, mesmo que os consumidores estejam temporariamente indisponíveis.

Em resumo, Pub/Sub é sobre velocidade e imediatismo, enquanto Streams focam em durabilidade e controle.

Código-Fonte do Projeto

Você pode encontrar a implementação completa deste projeto no meu GitHub

Referências e Leitura Complementar

Redis Documentation: Pub/Sub – Guia oficial sobre o paradigma de mensageria publish/subscribe.

Redis Documentation: Streams – Análise detalhada do tipo de dado Stream e de consumer groups.

StackExchange.Redis GitHub – Documentação do principal cliente Redis para .NET utilizado neste projeto.

Microsoft Docs: Minimal APIs Overview – Referência para a criação de APIs de alta performance com .NET 10.

Docker Docs: Compose File Reference – Guia para configurar aplicações com múltiplos containers.

Otimizando Imagens para a Web com Go e Docker

Sat, 03 Jan 2026 00:00:00 +0000

Quando decidi criar meu próprio blog, eu já tinha em mente que precisaria ser responsável pela hospedagem das imagens que usaria. Seria uma ótima oportunidade de aprender mais sobre o AWS S3, algo que já estava no meu roadmap de estudos, e trabalhar em um projeto real é, quase sempre, a melhor forma de aprender.

Assim que comecei a escrever o primeiro post, criei minha conta na AWS e bucket no S3 que usaria no blog. Porém, antes de começar a explorar o mar de configurações e possíveis otimizações, eu sabia que precisava otimizar minhas imagens. Existem milhares de serviços online que fazem isso, mas onde estaria a diversão? Eu queria algo local, rápido, customizado e que não dependesse de terceiros.

Decidi, então, construir o ImagePipe: uma ferramenta de CLI que converte imagens para WebP, redimensiona para um limite seguro de 1600px e pode ser executada em qualquer lugar via Docker.

Por que WebP e 1600px?

O WebP é um formato moderno que oferece um equilíbrio incrível entre qualidade e desempenho:

Compressão Superior: Reduz o tamanho do arquivo em até 35% comparado ao JPEG.
Versatilidade: Suporta transparência (como PNG) e animações (como GIF) com arquivos muito menores.
SEO e Performance: Imagens leves melhoram o LCP, um fator crucial para o ranking do Google.
Resolução Inteligente: Limitar a largura a 1600px garante que a imagem seja nítida em telas grandes sem carregar pixels desnecessários que pesam no carregamento mobile.

Criando o projeto em Go

O primeiro passo foi estruturar o módulo em Go. No terminal:

mkdir ImagePipe
cd ImagePipe
go mod init github.com/JoaoOliveira889/ImagePipe

Dentro dessa pasta, vamos criar um arquivo main.go e colar o código abaixo. O programa, por default, reduz a qualidade em 75%, mas esse valor pode ser alterado via parâmetro na execução. Também será possível executar localmente sem docker via go run main.go e então arrastar a imagem para o terminal ou digitar o full path.

Via docker, vamos configurar para que possa ser chamado de qualquer pasta do SO. Por exemplo: se estiver na pasta pictures, so basta executar imagepipe photo.jpeg para gerar a versão otimizada.

package main

import (
 "bufio"
 "fmt"
 "image"
 _ "image/jpeg" // Register JPEG decoder for image.Decode
 _ "image/png" // Register PNG decoder for image.Decode
 "os"
 "path/filepath"
 "strconv"
 "strings"
 "time"

 "github.com/chai2010/webp" // WebP encoder library
 "golang.org/x/image/draw" // High-performance image scaling package
)

func main() {
 var inputPath string
 var qualityStr string
 quality := 75 // Default compression quality

 // 1. Input Handling: Supports both CLI arguments and interactive mode
 if len(os.Args) >= 2 {
 inputPath = os.Args[1]
 if len(os.Args) > 2 {
 qualityStr = os.Args[2]
 }
 } else {
 // Interactive Mode for local execution
 fmt.Println("Image to WebP Optimizer")
 fmt.Println("-----------------------")
 fmt.Print("\nPath (File or Folder): ")

 scanner := bufio.NewScanner(os.Stdin)
 if scanner.Scan() {
 inputPath = scanner.Text()
 }

 fmt.Print("Quality (Default 75): ")
 if scanner.Scan() {
 qualityStr = scanner.Text()
 }
 }

 // Clean path: Remove quotes and handle escaped spaces (common when dragging files to terminal)
 inputPath = strings.Trim(strings.TrimSpace(inputPath), "\"'")
 inputPath = strings.ReplaceAll(inputPath, `\ `, " ")

 if inputPath == "" {
 fmt.Println("Error: No path provided.")
 return
 }

 // Parse quality string to integer
 if qualityStr != "" {
 if q, err := strconv.Atoi(strings.TrimSpace(qualityStr)); err == nil {
 quality = q
 }
 }

 // 2. Path Analysis: Check if target is a single file or a directory
 fileInfo, err := os.Stat(inputPath)
 if err != nil {
 fmt.Printf("Error: Path '%s' not found.\n", inputPath)
 return
 }

 if fileInfo.IsDir() {
 // Batch Processing
 fmt.Printf("\nProcessing folder: %s\n", inputPath)
 files, _ := os.ReadDir(inputPath)
 for _, f := range files {
 ext := strings.ToLower(filepath.Ext(f.Name()))
 // Filter supported image formats
 if ext == ".jpg" || ext == ".jpeg" || ext == ".png" {
 processImage(filepath.Join(inputPath, f.Name()), quality)
 }
 }
 } else {
 // Single file processing
 processImage(inputPath, quality)
 }
}

// processImage handles the decoding, resizing, and WebP encoding logic
func processImage(path string, quality int) {
 file, err := os.Open(path)
 if err != nil {
 fmt.Printf("Error opening %s: %v\n", path, err)
 return
 }
 defer file.Close()

 inInfo, _ := file.Stat()
 img, _, err := image.Decode(file) // Decode the original image buffer
 if err != nil {
 fmt.Printf("Error decoding %s: Please use JPG or PNG\n", path)
 return
 }

 // 3. Resolution Optimization: Caps width at 1600px
 bounds := img.Bounds()
 if bounds.Dx() > 1600 {
 newW := 1600
 // Calculate height maintaining the original aspect ratio
 newH := (bounds.Dy() * newW) / bounds.Dx()

 dst := image.NewRGBA(image.Rect(0, 0, newW, newH))

 // Use Catmull-Rom resampling for high-quality downscaling
 draw.CatmullRom.Scale(dst, dst.Bounds(), img, bounds, draw.Over, nil)
 img = dst
 }

 // 4. Output Creation: Append timestamp to filename to prevent overwriting
 ts := time.Now().Format("150405")
 outPath := strings.TrimSuffix(path, filepath.Ext(path)) + "_" + ts + ".webp"

 outFile, err := os.Create(outPath)
 if err != nil {
 fmt.Printf("Error creating output file: %v\n", err)
 return
 }
 defer outFile.Close()

 // 5. WebP Encoding: Apply final compression
 err = webp.Encode(outFile, img, &webp.Options{Quality: float32(quality)})
 if err != nil {
 fmt.Printf("Error encoding WebP: %v\n", err)
 return
 }

 // 6. Performance Report: Calculate and display size reduction
 outInfo, _ := os.Stat(outPath)
 savings := float64(inInfo.Size()-outInfo.Size()) / float64(inInfo.Size()) * 100
 fmt.Printf("✔ %s | Reduced: %.1f%% (Final: %d KB)\n",
 filepath.Base(outPath),
 savings,
 outInfo.Size()/1024,
 )
}

Eu defini para trabalhar apenas com imagens em PNG e JPEG. Se precisar adicionar outros formatos, é so acrescentar aqui:

"image"
 _ "image/jpeg"
 _ "image/png"

Instalando dependências

Agora, na pasta do projeto, vamos instalar as duas dependências:

go get github.com/chai2010/webp
go get golang.org/x/image/draw
go mod tidy

Com isso, já é possível executar o projeto com:

go run main.go

No terminal, basta arrastar a imagem a ser convertida ou passar o full patch. Em seguida, será perguntado se deseja alterar a qualidade padrão. Se quiser, informe o novo valor; caso contrário, pressione Enter para manter o padrão e executar o programa.

Rodando via Docker (chamando de qualquer pasta)

Eu não quero repetir o fluxo manual toda vez que precisar preparar imagens para publicar no S3. Então, empacotei a ferramenta em um Docker Multi-stage build. Isso gera uma imagem final extremamente leve, contendo apenas o binário necessário.

O Dockerfile:

# Stage 1: Build the binary
FROM golang:1.25.5-alpine AS builder

# Install build dependencies for CGO
RUN apk add --no-cache gcc musl-dev

WORKDIR /app

# Copy dependency files
COPY go.mod go.sum ./
RUN go mod download

# Copy the rest of the source code
COPY . .

# IMPORTANT: We use TARGETARCH to make this work on any machine
ARG TARGETARCH
RUN CGO_ENABLED=1 GOOS=linux GOARCH=$TARGETARCH go build -o imagepipe .

# Stage 2: Final lightweight image
FROM alpine:latest
RUN apk add --no-cache libc6-compat

WORKDIR /data
COPY --from=builder /app/imagepipe /usr/local/bin/imagepipe

ENTRYPOINT ["imagepipe"]

Agora, basta construir a imagem

docker build -t imagepipe .

Facilitando o uso com Shell Functions

Como o objetivo é conseguir chamar a partir de qualquer pasta, vamos configurar uma função no shell. Vou usar o Neovim para editar o ~/.zshrc, mas você pode usar o editor que preferir

nvim ~/.zshrc

No final do arquivo, adicione

imagepipe() {
 docker run --rm -it -v "$(pwd)":/data imagepipe "$1" "$2"
}

O que esse comando faz?

–rm: Remove o container após o uso, mantendo seu sistema limpo.
-v “$(pwd)”:/data: Mapeia a sua pasta atual para dentro do container. Assim, o ImagePipe lê suas fotos locais e salva os resultados na mesma pasta.
$1 e $2: São os argumentos de caminho e qualidade que você passa no terminal.

Agora vamos fazer o reload do shell

source ~/.zshrc

Resultado Final

Para executar via Docker, basta usar um dos comandos abaixo na pasta que contém as imagens

Objetivo	Comando
Converter uma imagem específica	imagepipe photo.jpg
Definir uma qualidade específica (90%)	imagepipe photo.jpg 90
Otimizar todas imagens da pasta	imagepipe .

O programa gera um arquivo .webp com um timestamp no nome, garantindo que suas imagens originais nunca sejam sobrescritas.

Conclusão

Com esse projeto simples, eu consigo otimizar rapidamente minhas imagens para subir no S3 sem depender de nenhum sistema externo, e ainda consigo adaptar o fluxo para diferentes cenários sempre que precisar. Não é sobre reinventar a roda, é sobre criar algo útil, divertido e totalmente ajustado às minhas necessidades.

Links e Referências

Projeto: Repositório no GitHub
Libs: Chai2010/WebP | Go Draw

Por que todo desenvolvedor deveria ter um blog (e como criei o meu)

Thu, 01 Jan 2026 00:00:00 +0000

Por que decidi criar meu próprio blog?

Há algum tempo assisti ao Fábio Akita falando sobre a importância de programadores criarem seus próprios blogs pessoais. Seja para compartilhar um projeto, documentar estudos ou até tentar a sorte como influenciador, no fim doesn’t matter. O que realmente importa é o exercício da escrita. Se for sobre algo que você goste ou deseja registrar, o processo deixa de ser penoso e se torna prazeroso.

Foi aí que percebi que criar essas “anotações” realmente me ajudam a fixar melhor o que estou aprendendo. Essa prática é validada por estudos da neurociência e da psicologia cognitiva: o ato de tomar notas é uma das ferramentas mais eficazes para a consolidação da memória. A ideia é basicamente dizer para o cérebro que aquilo que você está escrevendo é importante. Quando você escreve algo com suas próprias palavras, você está processando a informação e cria conexões neurais mais fortes. O artigo Listening and note takin explica bem sobre.

Além disso, existe o conceito do “backup da mente”. Se daqui a algum tempo eu precisar refazer uma tarefa ou aplicar um conceito antigo, saberei exatamente onde procurar.

A busca pela ferramenta ideal: Do Notion ao Obsidian

O fracasso com o Notion

Comecei criando minhas primeiras notas no Notion, mas acabei me perdendo nas customizações. O Notion é excelente com suas milhares de possibilidades, que foi justamente o motivo do meu fracasso. Passei mais tempo estudando como criar templates, interligar notas, criar banco de dados, do que realmente escrevendo.

Além disso, o fato de tudo estar vinculado à plataforma me incomodava, nada era realmente “meu”. O estalo final veio quando tentei abrir uma nota sem conexão e não consegui, pois estava tudo na nuvem. Para criar um “backup do meu cérebro”, eu precisava ser dono da informação.

A simplicidade do Obsidian

Comecei a pesquisar por uma alternativa, que fosse simples e me desse controle total, foi ai que conheci o Obsidian. Ele é um editor visual de Markdown que, embora permita o uso de plugins poderosos, cumpre perfeitamente a função base que eu buscava: ser fácil e personalizável.

Sem entrar em muito detalhes do Obsidian, o que fiz foi basicamente instalar alguns plugins básicos que deixassem meu fluxo agradável, sem gerar dependência. Se o Obsidian deixar de existir amanhã, minhas notas continuam comigo e podem ser lidas em qualquer editor de texto. Tudo está offline, sincronizado entre meus dispositivos e sem dependência de nuvens proprietárias.

Compartilhando o conhecimento: LinkedIn vs. Dev.To

Ao tomar gosto pela escrita, decidi compartilhar minhas notas. Escrever para você mesmo é libertador, sem pressão por frequência, sem a necessidade de agradar a ninguém. Claro, não tem nenhum problema em querer escrever artigos com o intuito de ficar famoso, ou virar um “influencer”, o único problema é que a maioria das pessoas vai se frustrar, afinal você precisa ter uma boa cadência de postagens, estar sempre interagindo com seu público, é claro tomar cuidado para não ser “cancelado”.

Tentei inicialmente o LinkedIn, mas a experiência foi ruim para conteúdos técnicos. A falta de suporte nativo ao Markdown torna a formatação de códigos um processo penoso. Funciona bem para textos curtos ou relatos de experiência, mas para códigos, deixa a desejar.

Resolvi testar então a plataforma Dev.To, é de cara já gostei muito porque os post são escritos nativamente com Markdown, (bastou um “copiar e colar” das minhas notas). A plataforma oferece um bom dashboard de métricas e gera um engajamento orgânico interessante. Pretendo continuar usando o Dev.To para artigos técnicos em inglês, visando melhorar meu vocabulário e soft skills.

No entanto, este blog pessoal será em português. Quero aprimorar minha comunicação nativa e manter meu “segundo cérebro” acessível na minha língua materna.

Blog Engine Hugo com Hextra

Foi então que lendo justamente um post no blog do Akita, sobre o seu novo blog, que conheci a ferramenta perfeita para o meu propósito o Hugo. Ele é um gerador de sites estáticos que transforma Markdown em HTML. Usei o tema Hextra pela simplicidade e recursos como busca poderosa e tags.

Instalação e Configuração rápida

Seguindo a premissa de “primeiro faça, depois melhore”, a instalação foi simples. No macOS, via Homebrew (outros sistemas só conferir a documentação oficial)

brew install hugo

Para criar o site e configurar o tema

hugo new site myblog --format=yaml

Na pasta onde criou seu blog, faça a Inicialização do Hextra theme

cd myblog
hugo mod init github.com/username/myblog
hugo mod get github.com/imfing/hextra

No arquivo hugo.yaml, basta adicionar o módulo

module:
 imports:
 - path: github.com/imfing/hextra

Para criar o menu de navegação, após importar o hextra no hugo.yaml, adicione

# Navigation Menu
menu:
 main:
 - name: About
 pageRef: /about
 weight: 1
 - name: Contact ↗
 url: ""
 weight: 2
 - name: Search
 weight: 3
 params:
 type: search
 - name: Rss
 weight: 4
 url: "/index.xml"
 params:
 icon: rss

Criando as primeiras páginas para test

hugo new content/_index.md
hugo new content/docs/_index.md

Para rodar o blog localmente, inicie o servidor do Hugo e acesse http://localhost:1313

hugo server --buildDrafts --disableFastRender

Se o comando executar sem erros, você verá o site carregado no navegador, como na imagem abaixo:

Eu organizo os posts em content/blog por ano e mês (ex.: 2026/01). Assim eu consigo publicar rápido, manter o conteúdo organizado, e deixar o Hugo cuidar do index e da navegação entre as postagens.

O Hextra possui uma documentação muito completa com todas as opções de configuração. Você pode consultá-la aqui: Guia de configuração do Hextra.

Comandos extras Para atualizar todos os módulos do Hugo no projeto para a versão mais recente:

hugo mod get -u

Para atualizar apenas o tema Hextra para a versão mais recente:

hugo mod get -u github.com/imfing/hextra

Opcionalmente, após atualizar, você pode garantir que o go.sum e dependências estejam consistentes:

hugo mod tidy

Deploy descomplicado com Netlify

Agora que está tudo configurado e rodando localmente, o próximo passo é fazer o deploy, eu decidir escolher a Netlify. Já tinha visto muitos desenvolvedores elogiando a simplicidade do processo e, de fato, me surpreendi. Bastou subir o projeto no GitHub e conectar a conta. Em segundos, o blog estava online com uma URL temporária.

Para usar meu domínio próprio, configurei os registros DNS da seguinte forma

Registro A @ 75.2.60.5
Registro CNAME www joaooliveira.netlify.app

Em poucos segundos, o blog estava acessível em: https://joaooliveira.net

Conclusão

Alcancei o equilíbrio que buscava: um blog pessoal com baixo esforço de manutenção e alto controle do conteúdo. O foco agora é escrever, sem me perder em customizações infinitas. O combo Hugo + Hextra + Netlify entrega simplicidade agora e flexibilidade para o futuro.

Links e Referências

Projeto

Repositório no GitHub: Código-fonte, configurações e estrutura de pastas deste blog.

Referências Úteis

Meu novo blog: como eu fiz: Artigo de Fabio Akita que serviu de inspiração para a escolha da stack.
Documentação Oficial do Hextra: Guia completo para configuração e customização do tema utilizado.

Joao Oliveira – Joao Oliveira

Construindo uma API em Go para gerenciar arquivos no Amazon S3

O que essa API faz

Arquitetura e Estrutura do Projeto

Como cada parte se conecta

Estrutura de diretórios

Decisões importantes nessa estrutura

Endpoints

Files

Buckets

Pontos de destaque e decisões técnicas

UUID v7 para nomes de arquivos

Streaming para evitar picos de memória

Validação real de tipo de arquivo (MIME)

Timeouts como proteção de recursos

Inicializando o projeto

Gerenciamento de Dependências

Camada de Domínio

Entidades

Interface do Repositório

Camada de Infraestrutura

Destaques técnicos na Infraestrutura

Camada de Serviço

Destaques técnicos no Serviço

Concorrência com errgroup

Segurança: validação de tipo de arquivo

Resiliência: timeouts por operação

Encapsulamento e injeção de dependência

Camada de Handler

Decisões técnicas no handler

O ponto de entrada (main)

Destaques técnicos na main

Segurança e configuração: gerenciando credenciais

Arquivo .env (desenvolvimento local)

Obtendo Credenciais no Console AWS (IAM)

Middlewares: observabilidade e resiliência

Logging estruturado

Controle de timeout

Destaques técnicos Middlewares

Testes Unitários

Implementando os Testes do Serviço

Destaques técnicos nos testes

Automação com GitHub Actions

Configurando o Workflow (go.yml)

Destaques técnicos na Automação

Configurações Centralizadas

Erros Semânticos

Destaques técnicos nos Erros

Containerização com Docker

Dockerfile otimizado

Orquestração com Docker Compose

Destaques técnicos Docker

Comandos Úteis

Conclusão

Links do projeto

Referências

Redis Implementando Pub/Sub e Streams em .NET 10

Conceitos: Pub/Sub vs Streams

Configuração do Ambiente

Configuração do Docker

Implementação do Projeto

Model

Interface

Service

Workers

Program.cs

Comparação

Testando os endpoints

Pub/Sub Broadcast

Simular Pub/Sub sem Worker

Stream Log

Peek History on Stream

Stream Process

Fluxo do Processo

Conclusão

Código-Fonte do Projeto

Referências e Leitura Complementar

Otimizando Imagens para a Web com Go e Docker

Por que WebP e 1600px?

Criando o projeto em Go

Destaques técnicos na `main`

Arquivo `.env` (desenvolvimento local)