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 è 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/webpogithub.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.