Imagina un escenario habitual: tu servicio en Go vuelca periódicamente a disco una configuración actualizada o unos tokens de autorización, mientras un proceso en segundo plano (por ejemplo, Envoy o un agente de métricas) vigila el fichero con inotify y lo relee en cuanto cambia. Con la librería estándar de Go, la mano se va sola a la función de siempre:
err := os.WriteFile("/etc/app/config.json", data, 0644)
A primera vista parece limpio y seguro. Pero un día, en producción, salta un fallo inexplicable: el servicio en segundo plano se cae con el error unexpected end of JSON input. Abres el fichero en el servidor y ahí dentro hay un JSON perfectamente válido. Acabas de cazar una condición de carrera clásica del sistema de ficheros (truncate race condition).
La trampa de O_TRUNC: por qué el fichero queda vacío durante un instante
Bajo el capó, os.WriteFile ejecuta una llamada al sistema open con los flags os.O_WRONLY | os.O_CREATE | os.O_TRUNC.
Y justo ahí es donde se esconde la trampa:
- El flag
O_TRUNCdel kernel de Linux pone a cero la longitud del fichero existente en el mismo instante en que abre el descriptor. - Solo después empieza el runtime de Go a copiar los nuevos bytes desde la RAM hacia el búfer del sistema de ficheros.
- El proceso termina con la llamada
close.
Si en esa ventana microscópica un hilo paralelo o un demonio externo intenta leer el fichero, se lo encontrará vacío (0 bytes) o escrito a medias. Para cualquier parser, eso es un desastre seguro.
Cómo funciona renameio: fiabilidad mediante POSIX rename
Para que el lector vea siempre o bien la versión antigua completa o bien la nueva completa, se aplica el patrón de sustitución atómica. En el ecosistema Go, la referencia es la librería de Google renameio y su segunda rama renameio/v2.
La librería sigue una secuencia estricta de pasos:
- Crea un fichero temporal en el mismo directorio donde reside el fichero de destino.
- Escribe los datos nuevos en ese fichero temporal.
- Llama a la sincronización
fsyncpara forzar el volcado de la caché de memoria al disco. - Ejecuta la llamada atómica al sistema
rename(2). El kernel de Linux simplemente cambia el puntero en el directorio hacia el nuevoinode. Para los procesos externos no existe ningún estado intermedio. - Borra automáticamente el fichero temporal si se produce cualquier error.
En nuestro análisis sobre cómo funciona el testing de ficheros en Go sin carpetas temporales mediante fstest.MapFS, vimos cómo aislar las pruebas. El aislamiento real en disco en producción se apoya precisamente en esta atomicidad.
Veamos cómo queda la escritura segura con renameio/v2:
package main
import (
"log"
"github.com/google/renameio/v2"
)
func updateConfig(filePath string, payload []byte) error {
// Sobrescribimos el fichero de forma atómica respetando la umask del proceso
if err := renameio.WriteFile(filePath, payload, 0644); err != nil {
log.Printf("Сбой атомарного обновления: %v", err)
return err
}
return nil
}
Aquí renameio.WriteFile sustituye directamente a os.WriteFile con la misma firma, encargándose por debajo de crear el temporal, sincronizarlo y reemplazar el destino en una sola operación atómica.
Para escribir grandes volúmenes de datos en flujo continuo dispones del tipo PendingFile:
t, err := renameio.TempFile("", "/etc/app/config.json")
if err != nil {
return err
}
defer t.Cleanup()
if _, err := t.Write(payload); err != nil {
return err
}
return t.CloseAtomicallyReplace()
Con TempFile abres el fichero temporal en la misma ruta, vas escribiendo por bloques con t.Write, te aseguras de limpiar residuos si algo falla gracias a defer t.Cleanup() y solo al final haces el intercambio atómico con CloseAtomicallyReplace().
Qué cambió en la v2 y dónde están los límites del método
La principal diferencia de renameio/v2 frente a la primera versión es el respeto correcto por la máscara de permisos del sistema umask. En la v1, WriteFile aplicaba los permisos de forma rígida. La versión v2 aplica la umask exactamente igual que el os.WriteFile estándar. Si necesitas el comportamiento antiguo, basta con pasar la opción renameio.IgnoreUmask().
La llamada al sistema rename solo garantiza atomicidad dentro de un mismo volumen de disco montado. Si el fichero temporal se crea en /tmp pero el destino está en otro volumen como /var/data, el sistema devolverá el error EXDEV. Mantén siempre el fichero temporal junto al de destino.
Frente a condiciones de carrera de aplicación y configuraciones vacías en producción, combinar un fichero temporal y renameio/v2 protege de forma impecable.

