Gestire il formato WebP in Go

In Go la gestione di WebP richiede qualche decisione in più rispetto ad altri linguaggi, perché la libreria standard si ferma alla soglia del formato.

Go di Gabriele Romanato

Go è una scelta eccellente per i servizi che elaborano immagini: un singolo binario statico, una libreria standard con i pacchetti image, image/jpeg e image/png, goroutine a basso costo per parallelizzare il lavoro e un server HTTP pronto per la produzione. Con WebP, però, la situazione è meno lineare di quanto ci si aspetterebbe: la libreria standard non lo supporta, e il pacchetto ufficiale esterno golang.org/x/image/webp sa soltanto decodificare. Per la codifica bisogna scegliere tra binding cgo a libwebp, encoder scritti in Go puro e soluzioni ibride.

In questo articolo faremo una panoramica delle opzioni e poi costruiremo un servizio completo: un parser dell'intestazione scritto da zero, la decodifica con x/image/webp, la codifica con github.com/gen2brain/webp, la correzione dell'orientamento EXIF, il ridimensionamento, la lettura delle animazioni, un handler HTTP con negoziazione del formato e un convertitore parallelo per gli archivi esistenti.

Le opzioni disponibili

Prima di scrivere codice conviene capire il panorama, perché la scelta della libreria ha conseguenze sul processo di build e sul deploy.

  • golang.org/x/image/webp: mantenuto dal team di Go, scritto in Go puro, supporta la decodifica di immagini con e senza perdita e con canale alfa. Non codifica e non gestisce le animazioni.
  • Binding cgo a libwebp, come github.com/chai2010/webp o github.com/kolesa-team/go-webp: offrono l'encoder di riferimento con tutte le opzioni, ma richiedono un compilatore C, rendono più complessa la cross-compilazione e producono binari non più statici.
  • Encoder in Go puro, come github.com/HugoSmits86/nativewebp: nessuna dipendenza nativa, ma tipicamente limitati alla compressione senza perdita o meno efficienti di libwebp.
  • github.com/gen2brain/webp: usa libwebp compilata in WebAssembly ed eseguita con il runtime wazero, quindi senza cgo. Se sul sistema è installata la libreria condivisa di libwebp la carica dinamicamente, altrimenti ricorre al modulo WASM incluso. Codifica con e senza perdita e decodifica anche le animazioni.

Per questo articolo useremo gen2brain/webp per la codifica, perché conserva il grande vantaggio di Go, la compilazione senza toolchain C, pur affidandosi all'encoder ufficiale. Per la decodifica statica useremo x/image/webp, la dipendenza più leggera e collaudata.

go mod init example.com/webpservice
go get golang.org/x/image@latest
go get github.com/gen2brain/webp@latest

La struttura di un file WebP

Un file WebP è un contenitore RIFF: quattro byte RIFF, la dimensione del resto del file come intero a 32 bit little-endian, quattro byte WEBP e poi una sequenza di chunk, ognuno con un identificatore di quattro caratteri, una dimensione e un contenuto. Il primo chunk indica la variante. VP8 , con lo spazio, è un'immagine con perdita senza alfa, con le dimensioni su 14 bit dopo il codice di sincronizzazione 9d 01 2a. VP8L è un'immagine senza perdita: dopo il byte 0x2f, 28 bit contengono larghezza e altezza meno uno e un bit successivo segnala l'alfa. VP8X è il formato esteso, necessario per alfa con perdita, profili ICC, EXIF, XMP e animazioni, con un byte di flag e le dimensioni della tela su 24 bit.

Un parser dell'intestazione

Leggere questi pochi byte ci permette di validare i file in ingresso, di distinguere un'animazione da un'immagine statica e di conoscere le dimensioni senza allocare un solo pixel. Il pacchetto encoding/binary fa tutto il lavoro.

// webpinfo/webpinfo.go
package webpinfo

import (
	"encoding/binary"
	"errors"
	"io"
)

// Varianti del formato
const (
	FormatLossy    = "lossy"
	FormatLossless = "lossless"
	FormatExtended = "extended"
)

const (
	flagICC       = 0x20
	flagAlpha     = 0x10
	flagEXIF      = 0x08
	flagXMP       = 0x04
	flagAnimation = 0x02
)

// ErrNotWebP indica che i dati non sono un file WebP riconoscibile
var ErrNotWebP = errors.New("webpinfo: not a WebP file")

type Info struct {
	Format   string
	Width    int
	Height   int
	Alpha    bool
	Animated bool
	ICC      bool
	EXIF     bool
	XMP      bool
}

// Parse legge solo i primi 30 byte di r
func Parse(r io.Reader) (Info, error) {
	var header [30]byte
	if _, err := io.ReadFull(r, header[:]); err != nil {
		return Info{}, ErrNotWebP
	}
	return ParseBytes(header[:])
}

func ParseBytes(data []byte) (Info, error) {
	if len(data) < 30 || string(data[0:4]) != "RIFF" || string(data[8:12]) != "WEBP" {
		return Info{}, ErrNotWebP
	}

	switch string(data[12:16]) {
	case "VP8 ":
		// Codice di sincronizzazione del fotogramma chiave
		if data[23] != 0x9d || data[24] != 0x01 || data[25] != 0x2a {
			return Info{}, ErrNotWebP
		}
		return Info{
			Format: FormatLossy,
			Width:  int(binary.LittleEndian.Uint16(data[26:]) & 0x3fff),
			Height: int(binary.LittleEndian.Uint16(data[28:]) & 0x3fff),
		}, nil

	case "VP8L":
		if data[20] != 0x2f {
			return Info{}, ErrNotWebP
		}
		bits := binary.LittleEndian.Uint32(data[21:])
		return Info{
			Format: FormatLossless,
			Width:  int(bits&0x3fff) + 1,
			Height: int((bits>>14)&0x3fff) + 1,
			Alpha:  (bits>>28)&0x1 == 1,
		}, nil

	case "VP8X":
		flags := data[20]
		return Info{
			Format:   FormatExtended,
			Width:    int(uint24(data[24:])) + 1,
			Height:   int(uint24(data[27:])) + 1,
			Alpha:    flags&flagAlpha != 0,
			Animated: flags&flagAnimation != 0,
			ICC:      flags&flagICC != 0,
			EXIF:     flags&flagEXIF != 0,
			XMP:      flags&flagXMP != 0,
		}, nil
	}

	return Info{}, ErrNotWebP
}

func uint24(b []byte) uint32 {
	return uint32(b[0]) | uint32(b[1])<<8 | uint32(b[2])<<16
}

L'errore sentinella ErrNotWebP permette al chiamante di distinguere con errors.Is un file non valido da altri problemi. La funzione Parse usa io.ReadFull, che garantisce di leggere esattamente il numero di byte richiesto oppure restituisce un errore: con un semplice Read potremmo ricevere meno dati del previsto da una connessione di rete.

Decodificare

Il pacchetto image della libreria standard ha un registro dei formati: ogni decoder si registra nella propria funzione init, e image.Decode sceglie quello giusto in base ai byte iniziali. Basta quindi un import con l'identificatore vuoto per rendere disponibile WebP. Allo stesso modo image.DecodeConfig restituisce dimensioni e modello di colore leggendo solo l'intestazione.

// imaging/decode.go
package imaging

import (
	"fmt"
	"image"
	"io"
	"os"

	// Registrazione dei decoder nel registro di image
	_ "image/gif"
	_ "image/jpeg"
	_ "image/png"

	_ "golang.org/x/image/webp"
)

// Open decodifica un file e restituisce l'immagine con il nome del formato
func Open(path string) (image.Image, string, error) {
	f, err := os.Open(path)
	if err != nil {
		return nil, "", err
	}
	defer f.Close()
	return image.Decode(f)
}

// Probe restituisce dimensioni e formato senza decodificare i pixel
func Probe(r io.Reader) (image.Config, string, error) {
	cfg, format, err := image.DecodeConfig(r)
	if err != nil {
		return image.Config{}, "", fmt.Errorf("probe: %w", err)
	}
	return cfg, format, nil
}

Il formato restituito sarà "webp", "jpeg", "png" o "gif". Un'immagine WebP con perdita viene decodificata come *image.YCbCr, o *image.NYCbCrA se ha l'alfa, mentre una senza perdita diventa *image.NRGBA. Non è un dettaglio accademico: la funzione di codifica dovrà gestire tutti questi tipi.

Codificare

Con gen2brain/webp la codifica segue l'idioma della libreria standard: una funzione Encode che scrive su un io.Writer, con una struttura di opzioni. I campi sono quattro: Quality da 0 a 100 (predefinito 75), Lossless, Method da 0 a 6 per il compromesso tra velocità e compressione (predefinito 4) ed Exact, che conserva i valori RGB dei pixel trasparenti.

// imaging/encode.go
package imaging

import (
	"bufio"
	"fmt"
	"image"
	"os"
	"path/filepath"

	"github.com/gen2brain/webp"
)

type EncodeOptions struct {
	Quality  int
	Lossless bool
	Method   int
}

// Photo è il profilo predefinito per le fotografie
var Photo = EncodeOptions{Quality: 80, Method: 4}

// Graphic è il profilo per loghi, icone e schermate
var Graphic = EncodeOptions{Quality: 100, Lossless: true, Method: 6}

// Save scrive su un file temporaneo e lo rinomina, così nessuno legge un file a metà
func Save(img image.Image, path string, opts EncodeOptions) error {
	tmp, err := os.CreateTemp(filepath.Dir(path), ".webp-*")
	if err != nil {
		return err
	}
	defer os.Remove(tmp.Name())

	w := bufio.NewWriter(tmp)
	err = webp.Encode(w, img, webp.Options{
		Quality:  opts.Quality,
		Lossless: opts.Lossless,
		Method:   opts.Method,
	})
	if err == nil {
		err = w.Flush()
	}
	if closeErr := tmp.Close(); err == nil {
		err = closeErr
	}
	if err != nil {
		return fmt.Errorf("encode %s: %w", path, err)
	}
	return os.Rename(tmp.Name(), path)
}

Il defer os.Remove rimuove il file temporaneo in caso di errore; se la rinomina riesce, la rimozione fallisce in silenzio perché il file non esiste più con quel nome. In modalità senza perdita il parametro Quality non degrada l'immagine ma indica quanto lavorare per comprimerla: Quality: 100 con Method: 6 produce il file più piccolo.

Per decidere quale profilo usare possiamo stimare se l'immagine è una grafica a colori piatti contando i colori distinti su un campione di pixel:

// imaging/classify.go
package imaging

import "image"

// IsFlatGraphic stima se l'immagine ha pochi colori distinti, come un logo o una schermata
func IsFlatGraphic(img image.Image, maxColors int) bool {
	bounds := img.Bounds()
	step := max(1, min(bounds.Dx(), bounds.Dy())/128)
	colors := make(map[uint64]struct{}, maxColors+1)

	for y := bounds.Min.Y; y < bounds.Max.Y; y += step {
		for x := bounds.Min.X; x < bounds.Max.X; x += step {
			r, g, b, a := img.At(x, y).RGBA()
			key := uint64(r>>8)<<24 | uint64(g>>8)<<16 | uint64(b>>8)<<8 | uint64(a>>8)
			colors[key] = struct{}{}
			if len(colors) > maxColors {
				return false
			}
		}
	}
	return true
}

Le funzioni predefinite min e max, disponibili da Go 1.21, rendono il calcolo del passo di campionamento più leggibile. Le fotografie superano la soglia di 256 colori in pochi campioni, quindi il costo della funzione è trascurabile.

L'orientamento EXIF

Le fotocamere e gli smartphone salvano spesso i pixel nell'orientamento del sensore e annotano la rotazione corretta nel tag EXIF Orientation. Il decoder JPEG della libreria standard ignora i metadati, e l'encoder WebP non li riscrive: se non applichiamo la rotazione, le foto scattate in verticale appariranno coricate. Non serve una libreria EXIF completa per leggere un solo tag: basta trovare il segmento APP1 del JPEG e percorrere la prima directory TIFF.

// imaging/orientation.go
package imaging

import (
	"bytes"
	"encoding/binary"
	"image"
	"image/draw"
)

// JPEGOrientation restituisce il valore del tag Orientation, oppure 1 se assente
func JPEGOrientation(data []byte) int {
	if len(data) < 4 || data[0] != 0xff || data[1] != 0xd8 {
		return 1
	}
	for pos := 2; pos+4 <= len(data); {
		if data[pos] != 0xff {
			return 1
		}
		marker := data[pos+1]
		size := int(binary.BigEndian.Uint16(data[pos+2:]))
		if marker == 0xda || pos+2+size > len(data) {
			// Inizio dei dati compressi: EXIF non trovato
			return 1
		}
		segment := data[pos+4 : pos+2+size]
		if marker == 0xe1 && bytes.HasPrefix(segment, []byte("Exif\x00\x00")) {
			return tiffOrientation(segment[6:])
		}
		pos += 2 + size
	}
	return 1
}

func tiffOrientation(tiff []byte) int {
	if len(tiff) < 8 {
		return 1
	}
	var order binary.ByteOrder
	switch string(tiff[0:2]) {
	case "II":
		order = binary.LittleEndian
	case "MM":
		order = binary.BigEndian
	default:
		return 1
	}
	offset := int(order.Uint32(tiff[4:]))
	if offset+2 > len(tiff) {
		return 1
	}
	count := int(order.Uint16(tiff[offset:]))
	for i := range count {
		entry := offset + 2 + i*12
		if entry+12 > len(tiff) {
			return 1
		}
		if order.Uint16(tiff[entry:]) == 0x0112 {
			if value := int(order.Uint16(tiff[entry+8:])); value >= 1 && value <= 8 {
				return value
			}
			return 1
		}
	}
	return 1
}

// ApplyOrientation restituisce una nuova immagine con i pixel orientati correttamente
func ApplyOrientation(img image.Image, orientation int) image.Image {
	if orientation <= 1 || orientation > 8 {
		return img
	}
	src := image.NewNRGBA(img.Bounds())
	draw.Draw(src, src.Bounds(), img, img.Bounds().Min, draw.Src)

	w, h := src.Bounds().Dx(), src.Bounds().Dy()
	// Le orientazioni da 5 a 8 scambiano larghezza e altezza
	dw, dh := w, h
	if orientation >= 5 {
		dw, dh = h, w
	}
	dst := image.NewNRGBA(image.Rect(0, 0, dw, dh))

	for y := range h {
		for x := range w {
			var dx, dy int
			switch orientation {
			case 2:
				dx, dy = w-1-x, y
			case 3:
				dx, dy = w-1-x, h-1-y
			case 4:
				dx, dy = x, h-1-y
			case 5:
				dx, dy = y, x
			case 6:
				dx, dy = h-1-y, x
			case 7:
				dx, dy = h-1-y, w-1-x
			case 8:
				dx, dy = y, w-1-x
			}
			si := src.PixOffset(x, y)
			di := dst.PixOffset(dx, dy)
			copy(dst.Pix[di:di+4], src.Pix[si:si+4])
		}
	}
	return dst
}

Il parser è difensivo: ogni accesso alla slice è preceduto da un controllo dei limiti, perché i dati provengono da file caricati dagli utenti e un EXIF malformato non deve mai causare un panic. Il blocco TIFF può essere in ordine little-endian (II, Intel) o big-endian (MM, Motorola), e l'interfaccia binary.ByteOrder ci permette di scrivere il codice una sola volta. La trasformazione copia ogni pixel nella posizione di destinazione corrispondente a una delle otto combinazioni di rotazione e specchiatura previste dallo standard.

Ridimensionare e generare le varianti

La libreria standard non include algoritmi di ridimensionamento di qualità, ma golang.org/x/image/draw sì: draw.CatmullRom è un interpolatore bicubico che dà risultati nitidi nella riduzione di scala, draw.ApproxBiLinear è molto più veloce e adatto alle anteprime.

// imaging/variants.go
package imaging

import (
	"fmt"
	"image"
	"path/filepath"
	"strings"

	"golang.org/x/image/draw"
)

var VariantWidths = []int{320, 640, 960, 1280, 1920}

type Variant struct {
	Width  int
	Height int
	Path   string
}

func Resize(img image.Image, width int) image.Image {
	b := img.Bounds()
	height := (b.Dy()*width + b.Dx()/2) / b.Dx()
	dst := image.NewNRGBA(image.Rect(0, 0, width, height))
	draw.CatmullRom.Scale(dst, dst.Bounds(), img, b, draw.Src, nil)
	return dst
}

func CreateVariants(img image.Image, name, outputDir string) ([]Variant, error) {
	var variants []Variant
	for _, width := range VariantWidths {
		// Nessuna variante più grande dell'originale
		if width > img.Bounds().Dx() {
			break
		}
		resized := Resize(img, width)
		opts := Photo
		if width <= 640 {
			opts.Quality = 75
		}
		path := filepath.Join(outputDir, fmt.Sprintf("%s-%d.webp", name, width))
		if err := Save(resized, path, opts); err != nil {
			return nil, err
		}
		variants = append(variants, Variant{Width: width, Height: resized.Bounds().Dy(), Path: path})
	}
	return variants, nil
}

func Srcset(variants []Variant, publicPath string) string {
	parts := make([]string, len(variants))
	for i, v := range variants {
		parts[i] = fmt.Sprintf("%s/%s %dw", publicPath, filepath.Base(v.Path), v.Width)
	}
	return strings.Join(parts, ", ")
}

L'operatore draw.Src copia anche il canale alfa così com'è, invece di comporlo su uno sfondo come farebbe draw.Over: è quello che vogliamo per conservare la trasparenza. Il risultato è sempre un *image.NRGBA, il tipo più naturale da passare all'encoder.

Animazioni

x/image/webp rifiuta i file animati, mentre gen2brain/webp espone DecodeAll, che restituisce una struttura con i fotogrammi in Image e i ritardi in millisecondi in Delay. La codifica di animazioni, invece, non è supportata da questa libreria: per convertire GIF in WebP animati in Go bisogna usare un binding cgo a libwebpmux oppure invocare lo strumento gif2webp di libwebp. Leggere le animazioni resta comunque utile, per esempio per estrarre una copertina statica o per validare un caricamento.

// imaging/animation.go
package imaging

import (
	"errors"
	"fmt"
	"io"
	"time"

	"github.com/gen2brain/webp"
)

type AnimationInfo struct {
	Frames   int
	Duration time.Duration
	Width    int
	Height   int
}

func InspectAnimation(r io.Reader, maxFrames int) (*webp.WEBP, AnimationInfo, error) {
	anim, err := webp.DecodeAll(r)
	if err != nil {
		return nil, AnimationInfo{}, fmt.Errorf("decode animation: %w", err)
	}
	if len(anim.Image) == 0 {
		return nil, AnimationInfo{}, errors.New("animation without frames")
	}
	if len(anim.Image) > maxFrames {
		return nil, AnimationInfo{}, fmt.Errorf("too many frames: %d", len(anim.Image))
	}

	var total time.Duration
	for _, delay := range anim.Delay {
		total += time.Duration(delay) * time.Millisecond
	}
	b := anim.Image[0].Bounds()
	return anim, AnimationInfo{
		Frames:   len(anim.Image),
		Duration: total,
		Width:    b.Dx(),
		Height:   b.Dy(),
	}, nil
}

// SavePoster salva il primo fotogramma come immagine statica
func SavePoster(anim *webp.WEBP, path string) error {
	return Save(anim.Image[0], path, Photo)
}

Va tenuto presente che DecodeAll decodifica tutti i fotogrammi in memoria, ciascuno come immagine completa: un'animazione di 300 fotogrammi a 1000 per 1000 pixel occupa circa 1,2 GB. Per questo, prima di chiamarla su un file non fidato, conviene leggere l'intestazione e verificare le dimensioni della tela.

Caricamenti sicuri

In un servizio HTTP ogni caricamento va trattato come ostile. Le difese da combinare sono tre: limitare i byte letti dal corpo della richiesta con http.MaxBytesReader, verificare le dimensioni dichiarate con image.DecodeConfig prima di decodificare, così da neutralizzare le decompression bomb, e determinare il formato dal contenuto, mai dall'estensione o dall'intestazione Content-Type inviata dal client.

// imaging/upload.go
package imaging

import (
	"bytes"
	"errors"
	"fmt"
	"image"
	"io"
	"slices"
)

const (
	MaxUploadBytes = 15 << 20
	MaxPixels      = 40_000_000
	MaxSide        = 2560
)

var (
	ErrTooLarge    = errors.New("image too large")
	ErrUnsupported = errors.New("unsupported image format")
	allowedFormats = []string{"jpeg", "png", "webp", "gif"}
)

// ProcessUpload valida, orienta, ridimensiona e ricodifica un'immagine caricata
func ProcessUpload(r io.Reader, target string) error {
	data, err := io.ReadAll(io.LimitReader(r, MaxUploadBytes+1))
	if err != nil {
		return err
	}
	if len(data) > MaxUploadBytes {
		return ErrTooLarge
	}

	// Prima solo l'intestazione: dimensioni e formato senza allocare i pixel
	cfg, format, err := image.DecodeConfig(bytes.NewReader(data))
	if err != nil {
		return fmt.Errorf("%w: %v", ErrUnsupported, err)
	}
	if !slices.Contains(allowedFormats, format) {
		return ErrUnsupported
	}
	if cfg.Width*cfg.Height > MaxPixels {
		return ErrTooLarge
	}

	img, _, err := image.Decode(bytes.NewReader(data))
	if err != nil {
		return fmt.Errorf("decode: %w", err)
	}
	if format == "jpeg" {
		img = ApplyOrientation(img, JPEGOrientation(data))
	}
	if b := img.Bounds(); max(b.Dx(), b.Dy()) > MaxSide {
		width := b.Dx() * MaxSide / max(b.Dx(), b.Dy())
		img = Resize(img, width)
	}

	opts := Photo
	if IsFlatGraphic(img, 256) {
		opts = Graphic
	}
	return Save(img, target, opts)
}

Leggere il file in memoria con un limite esplicito ci permette di passarlo due volte ai decoder, prima per la configurazione e poi per i pixel, e di cercare il segmento EXIF senza riaprire nulla. La ricodifica ha anche un effetto collaterale benefico per la privacy: il WebP prodotto non contiene metadati EXIF, quindi le coordinate GPS dello scatto non vengono pubblicate. Il rovescio della medaglia è che si perde anche l'eventuale profilo colore ICC: per immagini in spazi colore ampi come Display P3, la conversione andrebbe fatta in sRGB prima della codifica, con strumenti che gestiscono i profili.

Un handler HTTP con negoziazione del formato

Quando gli originali restano in JPEG o PNG, il server può servire WebP ai browser che lo dichiarano nell'intestazione Accept. La versione WebP viene generata alla prima richiesta e salvata su disco; se arrivano più richieste contemporanee per la stessa immagine, una sola goroutine esegue la conversione e le altre ne attendono il risultato. È lo schema reso celebre dal pacchetto singleflight, che qui implementiamo con pochi strumenti della libreria standard.

// server/handler.go
package server

import (
	"mime"
	"net/http"
	"os"
	"path"
	"path/filepath"
	"strings"
	"sync"

	"example.com/webpservice/imaging"
)

type call struct {
	done chan struct{}
	err  error
}

type ImageHandler struct {
	MediaDir string
	CacheDir string

	mu       sync.Mutex
	inFlight map[string]*call
}

func NewImageHandler(mediaDir, cacheDir string) *ImageHandler {
	return &ImageHandler{MediaDir: mediaDir, CacheDir: cacheDir, inFlight: map[string]*call{}}
}

func acceptsWebP(header string) bool {
	for _, part := range strings.Split(header, ",") {
		mediaType, params, err := mime.ParseMediaType(strings.TrimSpace(part))
		if err == nil && mediaType == "image/webp" {
			// q=0 significa rifiuto esplicito
			return params["q"] != "0" && params["q"] != "0.0"
		}
	}
	return false
}

func (h *ImageHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
	// path.Clean su un percorso assoluto elimina ogni tentativo di risalire con ../
	rel := strings.TrimPrefix(path.Clean("/"+r.URL.Path), "/")
	ext := strings.ToLower(filepath.Ext(rel))
	if ext != ".jpg" && ext != ".jpeg" && ext != ".png" {
		http.NotFound(w, r)
		return
	}
	source := filepath.Join(h.MediaDir, filepath.FromSlash(rel))
	info, err := os.Stat(source)
	if err != nil || info.IsDir() {
		http.NotFound(w, r)
		return
	}

	w.Header().Set("Vary", "Accept")
	w.Header().Set("Cache-Control", "public, max-age=86400")

	if !acceptsWebP(r.Header.Get("Accept")) {
		http.ServeFile(w, r, source)
		return
	}

	target := filepath.Join(h.CacheDir, strings.TrimSuffix(filepath.FromSlash(rel), ext)+".webp")
	if err := h.ensure(source, target, info); err != nil {
		http.Error(w, "conversion failed", http.StatusInternalServerError)
		return
	}
	w.Header().Set("Content-Type", "image/webp")
	http.ServeFile(w, r, target)
}

// ensure genera il file WebP se manca o se è più vecchio dell'originale
func (h *ImageHandler) ensure(source, target string, sourceInfo os.FileInfo) error {
	if cached, err := os.Stat(target); err == nil && !cached.ModTime().Before(sourceInfo.ModTime()) {
		return nil
	}

	h.mu.Lock()
	if c, ok := h.inFlight[target]; ok {
		h.mu.Unlock()
		<-c.done
		return c.err
	}
	c := &call{done: make(chan struct{})}
	h.inFlight[target] = c
	h.mu.Unlock()

	c.err = convert(source, target)

	h.mu.Lock()
	delete(h.inFlight, target)
	h.mu.Unlock()
	close(c.done)
	return c.err
}

func convert(source, target string) error {
	if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil {
		return err
	}
	data, err := os.ReadFile(source)
	if err != nil {
		return err
	}
	img, format, err := imaging.Open(source)
	if err != nil {
		return err
	}
	if format == "jpeg" {
		img = imaging.ApplyOrientation(img, imaging.JPEGOrientation(data))
	}
	return imaging.Save(img, target, imaging.Photo)
}

L'intestazione Vary: Accept è impostata per entrambe le risposte: indica alle cache intermedie che il contenuto dipende dall'intestazione Accept, e senza di essa una CDN potrebbe servire a tutti la prima versione memorizzata. Il canale done chiuso al termine della conversione sveglia contemporaneamente tutte le goroutine in attesa, che leggono l'errore dalla stessa struttura. http.ServeFile gestisce per noi le richieste condizionali con If-Modified-Since e le richieste parziali.

Il main che avvia il server è minimale. Chi usa Gin, come spesso accade nei servizi Go, può montare lo stesso handler con router.GET("/media/*path", gin.WrapH(http.StripPrefix("/media", handler))).

// cmd/server/main.go
package main

import (
	"log"
	"net/http"
	"time"

	"example.com/webpservice/server"
)

func main() {
	mux := http.NewServeMux()
	mux.Handle("/media/", http.StripPrefix("/media", server.NewImageHandler("media", "cache")))

	srv := &http.Server{
		Addr:              ":8080",
		Handler:           mux,
		ReadHeaderTimeout: 5 * time.Second,
		WriteTimeout:      30 * time.Second,
	}
	log.Printf("Server in ascolto su %s", srv.Addr)
	log.Fatal(srv.ListenAndServe())
}

Conversione parallela di un archivio

Per convertire un archivio esistente, le goroutine sono lo strumento naturale. Lanciarne una per file, però, significherebbe decodificare migliaia di immagini contemporaneamente ed esaurire la memoria. Lo schema corretto è un pool di worker di dimensione fissa che consuma i percorsi da un canale.

// cmd/convert/main.go
package main

import (
	"context"
	"flag"
	"fmt"
	"io/fs"
	"log"
	"os"
	"os/signal"
	"path/filepath"
	"runtime"
	"strings"
	"sync"
	"sync/atomic"

	"example.com/webpservice/imaging"
)

type job struct{ source, target string }

func main() {
	workers := flag.Int("workers", runtime.NumCPU(), "numero di conversioni parallele")
	flag.Parse()
	if flag.NArg() != 2 {
		log.Fatal("uso: convert [-workers N] <sorgente> <destinazione>")
	}
	sourceDir, targetDir := flag.Arg(0), flag.Arg(1)

	// Ctrl+C interrompe la scansione ma lascia terminare le conversioni in corso
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
	defer stop()

	jobs := make(chan job)
	var converted, failed, saved atomic.Int64
	var wg sync.WaitGroup

	for range *workers {
		wg.Add(1)
		go func() {
			defer wg.Done()
			for j := range jobs {
				before, after, err := convertFile(j.source, j.target)
				if err != nil {
					failed.Add(1)
					log.Printf("errore su %s: %v", j.source, err)
					continue
				}
				converted.Add(1)
				saved.Add(before - after)
			}
		}()
	}

	err := filepath.WalkDir(sourceDir, func(path string, d fs.DirEntry, err error) error {
		if err != nil || d.IsDir() {
			return err
		}
		ext := strings.ToLower(filepath.Ext(path))
		if ext != ".jpg" && ext != ".jpeg" && ext != ".png" {
			return nil
		}
		rel, _ := filepath.Rel(sourceDir, path)
		target := filepath.Join(targetDir, strings.TrimSuffix(rel, filepath.Ext(rel))+".webp")
		select {
		case jobs <- job{path, target}:
			return nil
		case <-ctx.Done():
			return ctx.Err()
		}
	})
	close(jobs)
	wg.Wait()

	if err != nil {
		log.Printf("scansione interrotta: %v", err)
	}
	fmt.Printf("convertiti %d, falliti %d, risparmiati %d KB\n", converted.Load(), failed.Load(), saved.Load()/1024)
}

func convertFile(source, target string) (int64, int64, error) {
	data, err := os.ReadFile(source)
	if err != nil {
		return 0, 0, err
	}
	img, format, err := imaging.Open(source)
	if err != nil {
		return 0, 0, err
	}
	if format == "jpeg" {
		img = imaging.ApplyOrientation(img, imaging.JPEGOrientation(data))
	}
	opts := imaging.Photo
	if imaging.IsFlatGraphic(img, 256) {
		opts = imaging.Graphic
	}
	if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil {
		return 0, 0, err
	}
	if err := imaging.Save(img, target, opts); err != nil {
		return 0, 0, err
	}
	info, err := os.Stat(target)
	if err != nil {
		return 0, 0, err
	}
	return int64(len(data)), info.Size(), nil
}

Il canale jobs non ha buffer: WalkDir si blocca finché un worker non è libero, quindi la scansione procede al ritmo delle conversioni e la memoria resta proporzionale al numero di worker. I contatori di tipo atomic.Int64 evitano un mutex per aggiornare le statistiche. Il costrutto for range *workers, introdotto in Go 1.22, itera un numero intero di volte.

Test

I test con tabella sono l'idioma di Go per verificare molti casi con poco codice. Qui generiamo immagini sintetiche, le codifichiamo nelle tre varianti e controlliamo che il parser restituisca ciò che ci aspettiamo; un secondo test verifica la trasformazione dell'orientamento su un'immagine di due per uno pixel.

// imaging/imaging_test.go
package imaging

import (
	"bytes"
	"image"
	"image/color"
	"testing"

	"github.com/gen2brain/webp"

	"example.com/webpservice/webpinfo"
)

func solid(alpha uint8) image.Image {
	img := image.NewNRGBA(image.Rect(0, 0, 123, 45))
	for i := 0; i < len(img.Pix); i += 4 {
		copy(img.Pix[i:], []byte{200, 30, 60, alpha})
	}
	return img
}

func TestParseVariants(t *testing.T) {
	tests := []struct {
		name    string
		img     image.Image
		options webp.Options
		format  string
		alpha   bool
	}{
		{"lossy", solid(255), webp.Options{Quality: 80}, webpinfo.FormatLossy, false},
		{"lossless alpha", solid(128), webp.Options{Lossless: true}, webpinfo.FormatLossless, true},
		{"lossy alpha", solid(128), webp.Options{Quality: 80}, webpinfo.FormatExtended, true},
	}
	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			var buf bytes.Buffer
			if err := webp.Encode(&buf, tt.img, tt.options); err != nil {
				t.Fatal(err)
			}
			info, err := webpinfo.Parse(&buf)
			if err != nil {
				t.Fatal(err)
			}
			if info.Format != tt.format || info.Alpha != tt.alpha || info.Width != 123 || info.Height != 45 {
				t.Errorf("got %+v", info)
			}
		})
	}
}

func TestApplyOrientation(t *testing.T) {
	src := image.NewNRGBA(image.Rect(0, 0, 2, 1))
	src.Set(0, 0, color.NRGBA{255, 0, 0, 255})
	src.Set(1, 0, color.NRGBA{0, 0, 255, 255})

	// Orientamento 6: rotazione di 90 gradi in senso orario
	got := ApplyOrientation(src, 6)
	if b := got.Bounds(); b.Dx() != 1 || b.Dy() != 2 {
		t.Fatalf("bounds %v", b)
	}
	if r, _, _, _ := got.At(0, 0).RGBA(); r>>8 != 255 {
		t.Errorf("il pixel rosso dovrebbe trovarsi in alto")
	}
}

func TestNotWebP(t *testing.T) {
	if _, err := webpinfo.ParseBytes([]byte("RIFF\x00\x00\x00\x00WAVEfmt ")); err == nil {
		t.Error("expected ErrNotWebP")
	}
}

Conclusioni

In Go la gestione di WebP richiede qualche decisione in più rispetto ad altri linguaggi, perché la libreria standard si ferma alla soglia del formato. La combinazione proposta in questo articolo, x/image/webp per decodificare e gen2brain/webp per codificare, mantiene intatta la compilazione senza cgo e affida la compressione all'encoder di riferimento; quando servono animazioni in uscita o il pieno controllo sui metadati, un binding cgo a libwebp diventa la strada obbligata. Il resto è Go idiomatico: un parser dell'intestazione con encoding/binary, la lettura difensiva dell'EXIF, interfacce io.Reader e io.Writer ovunque, un handler HTTP che negozia il formato e deduplica le conversioni concorrenti, un pool di worker che tiene sotto controllo la memoria. Sono mattoni piccoli e componibili, e proprio per questo facili da testare e da portare in produzione.