1# ADR 0013 — Mirror de fuentes: la URL es transporte, el `sha256` es la identidad
2
3- **Estado:** ACEPTADO — implementado en `crates/hammer-build/src/fetch.rs` y `scripts/fuentes/`.
4  **Ampliado por [ADR 0014](0014-distribucion-multiorigen.md)**: `HAMMER_MIRROR` y
5  `HAMMER_MIRROR_GIT` son LISTAS de orígenes, no una URL — un solo espejo propio reproducía
6  el punto único de fallo que este documento quería quitar.
7- **Fecha:** 2026-08-26
8- **Frontera:** `fetch_tarball` / `fetch_git`, `scripts/fuentes/mirror-poblar.sh`,
9  `scripts/fuentes/fuentes-vigia.sh`.
10
11## Contexto
12
13Dos recetas del corpus **no se pueden construir hoy, y no por culpa nuestra**:
14
15- `rsync` 3.4.4 → `download.samba.org` devuelve **404**. La tarball ya no está donde la receta la busca.
16- `musl` 1.2.5 → `musl.libc.org` **no responde** desde gioser (curl 000, connection reset).
17
18No es mala suerte: es el estado estacionario. Una distro que construye **todo desde fuente** tiene
19tantos puntos de fallo como fuentes distintas, y esos puntos son servidores de terceros que nadie
20nos prometió mantener. El problema sólo crece con el tiempo.
21
22### La medida, que es peor de lo que parece
23
24Sobre las 1167 recetas del árbol (561 tarball + 606 git, 79 hosts distintos):
25
26| recetas | host |
27|--------:|------|
28| **742** | `github.com` |
29| 104 | `download.kde.org` |
30| 68 | `download.gnome.org` |
31| 29 | `gitlab.freedesktop.org` |
32| 23 | `ftp.gnu.org` |
33
34**Un solo host sostiene el 64% del corpus.** Doce hosts sostienen el 89%. En el otro extremo, **43
35hosts sostienen exactamente una receta cada uno**: proyectos pequeños, dominios personales, cosas que
36se apagan sin aviso. Ahí es donde el bit-rot muerde despacio, y `musl.libc.org` y `download.samba.org`
37son justo eso.
38
39Dicho de otra forma: **la reproducibilidad del corpus está cerrada hacia adentro y completamente
40abierta hacia afuera.** Tenemos hashes de todo, verificación bit a bit y un store direccionado por
41contenido — apoyado sobre 79 servidores ajenos.
42
43## Decisión
44
45### 1. La URL nunca fue la identidad, y el código ya lo sabía
46
47`Recipe::hash_inputs` calcula:
48
49```rust
50let source_id = match self.source.kind()? {
51    SourceKind::Git { commit, .. } => format!("git:{commit}"),
52    SourceKind::Tarball { sha256, .. } => format!("tarball:{sha256}"),
53};
54```
55
56El `..` **descarta la URL**. Y la caché de tarballs se nombra `{sha256}.tar`, con un comentario que
57ya lo dice: *«dos URLs distintas con el mismo contenido se cachean una vez, y cambiar la URL sin
58cambiar el sha (mirror) no invalida la caché»*.
59
60⇒ **Añadir mirrors no re-hashea absolutamente nada.** No es una consecuencia afortunada: es que la
61identidad del contenido siempre estuvo en el `sha256` y el `commit`. La URL es una sugerencia sobre
62dónde buscar los bytes. Esto ya estaba diseñado; lo que faltaba era el mecanismo.
63
64### 2. Orden de resolución: caché local → mirror propio → upstream
65
66El mirror va **antes** que upstream, no después. Razones, en orden:
67
68- El `sha256` se verifica igual en los tres casos, así que **no hay diferencia de contenido posible**.
69  Preferir upstream «por pureza» no compra nada: compra latencia y un tercero en el camino.
70- Los workers de la granja son efímeros y descargan el corpus entero en cada ciclo. Pegarle 561
71  veces a servidores ajenos es a la vez frágil y de mala educación.
72- Un mirror sólo de rescate es un mirror que **nadie prueba**. Se descubre roto el día que hace falta,
73  que es exactamente el día en que no se puede arreglar.
74
75### 3. El mirror NO puede tapar el bit-rot: la vigilancia va SEPARADA
76
77Ésta es la parte que hay que hacer bien, y es una lección cara de este mismo repo.
78
79Un mirror que sirve calladamente lo que upstream ya perdió convierte un fallo **ruidoso** en
80**silencio**. Las URLs se irían muriendo una por una sin que nadie se entere, y el día que el mirror
81se pierda el corpus resultaría irreconstruible — con todos los indicadores en verde hasta ese
82momento. Es el mismo patrón que dejó el grafo de wlr congelado 17 días anunciando `121/121`: **una
83métrica que nadie refresca envejece hacia el optimismo.**
84
85Por eso **construir** y **vigilar upstream** son dos trabajos distintos y van en dos sitios distintos:
86
87- `hammer build` **nunca** avisa de que usó el mirror. No es su tarea y volvería el log inútil.
88- `scripts/fuentes/fuentes-vigia.sh` recorre las 1167 fuentes con `curl -I` (cabeceras, sin
89  descargar) y escribe `docs/state/fuentes-vigia.json`: qué URLs siguen vivas, cuáles dan 404,
90  cuáles no responden. **Lo corre el latido**, como el grafo de estado.
91
92Una URL muerta deja de ser una emergencia en mitad de un build y pasa a ser una línea en un informe.
93
94### 4. Poblar es un efecto secundario, no una tarea
95
96Toda descarga **verificada** se promueve al mirror. El mirror se llena solo, construyendo.
97`scripts/fuentes/mirror-poblar.sh` hace la carga inicial desde `work/tarballs` y sirve para
98rellenar lo que falte.
99
100El mirror vive en el Storage Box, bajo `hammer/fuentes/`, direccionado por contenido:
101`hammer/fuentes/{sha256}.tar`. Es el mismo Storage Box del respaldo (1 TiB, 938 G libres, ~€3,20/mes
102ya pagados) — no hay infraestructura nueva que mantener.
103
104### 5. ⛔ PROHIBIDO cambiar el `sha256` para «arreglar» una URL muerta
105
106La regla más importante del documento, porque es la tentación natural cuando un build falla con 404:
107buscar la tarball nueva, pegar el `sha256` nuevo, seguir adelante.
108
109**Eso no arregla una descarga: cambia lo que la distro construye.** Un `sha256` distinto es otro
110contenido — otra versión, otro tarball re-empaquetado, o un compromiso de upstream. La receta seguiría
111llamándose `rsync 3.4.4` y estaría construyendo otra cosa, con el agravante de que el artefacto
112resultante se sella como si tal cosa.
113
114Ante una URL muerta, en este orden:
115
1161. **Buscar los bytes originales** — el mirror, la caché de otra máquina, un mirror público conocido.
117   Si el `sha256` casa, se actualiza la URL y **listo, sin re-hasheo**.
1182. Si no aparecen en ningún sitio, es un **cambio de versión** con su propia auditoría: se mira qué
119   cambió, se actualiza `version` + `sha256`, y se acepta el re-hasheo en cascada que corresponda.
1203. Nunca, jamás, el paso 2 disfrazado de paso 1.
121
122## Cómo se activa
123
124```sh
125. scripts/fuentes/mirror-env.sh          # HAMMER_MIRROR + HAMMER_MIRROR_KEY
126flock work/.farm-build.lock ./target/release/hammer --store ./store build <receta>
127```
128
129**El mirror es ADITIVO: sin `HAMMER_MIRROR` el comportamiento es exactamente el de siempre.** No se
130hornea un default en el binario a propósito — apuntar por defecto a una máquina concreta convertiría
131un fallo de red en un fallo de `hammer` para cualquiera que clone el repo.
132
133⚠️ La ruta sftp lleva `/~/`. curl trata lo que sigue al host en `sftp://` como ruta **absoluta** del
134servidor: `…:23/hammer/fuentes` busca en la raíz y da «(78) Could not open remote file for reading»
135**aunque el fichero exista**, que es un error que parece de permisos o de ausencia y es de ruta.
136
137### Verificado de punta a punta, no por inspección
138
139Primer intento de prueba: construir `busybox` (upstream muerto) con el mirror puesto. Dijo `BUILD
140OK` **y no probó nada** — busybox ya estaba sellado, así que hubo cache-hit del artefacto y no se
141descargó un solo byte. La prueba válida es una receta cuyo artefacto NO exista:
142
143- receta efímera con el `sha256` de un tarball que **sí** está en el mirror,
144- y una URL upstream que **ni resuelve por DNS** (`https://este-host-no-existe.invalid/…`).
145
146Sin `HAMMER_MIRROR`: falla con `curl (6) Could not resolve host`. Con `HAMMER_MIRROR`: **sella**, y el
147artefacto tiene el contenido real. Los bytes no pudieron venir de ningún otro sitio.
148
149## Consecuencias
150
151- **Cero re-hasheos.** Verificado: recalculadas las 794 recetas del grafo wlr antes y después, 0 cambios.
152- El corpus deja de depender de que 79 terceros sigan sirviendo los mismos bytes.
153- **La concentración en `github.com` (64%) no la arregla este ADR** — la mitiga. Sigue siendo el
154  riesgo estructural mayor del proyecto y merece su propia decisión. ADR 0006 (commits pineados) ya
155  cubre la parte de que GitHub **regenera** los `archive/<tag>.tar.gz`, que es un problema distinto y
156  peor: ahí los bytes cambian sin que cambie la URL.
157- Aparece una dependencia nueva: el Storage Box. Es aceptable porque es **caché reconstruible**, no
158  la verdad: la verdad son las recetas en git. Si el mirror se pierde, se repuebla desde cualquier
159  máquina que tenga `work/tarballs`.
160
161## Fuentes git: bundles shallow por commit
162
163Los 606 repos por commit son el 52% de las fuentes y no los cubre el mirror de tarballs. Se espejan
164como **bundles**, en un espacio de nombres propio: `hammer/fuentes-git/{commit}.bundle` (571 commits
165distintos — hay commits compartidos entre colas, y se espeja uno solo).
166
167**La identidad es el commit y la verificación la hace git.** Al desempaquetar, git comprueba cada
168objeto contra su SHA: un bundle alterado no pasa. No hace falta índice ni un `sha256` aparte, igual
169que en los tarballs el nombre del fichero ES su verificación.
170
171### Shallow, no clones completos
172
173El bundle se genera desde un `git fetch --depth 1` del commit exacto. Para `act` son **9,3 MB en vez
174del repositorio entero**, y con 571 fuentes esa diferencia decide si el mirror cabe. Es legítimo
175porque **hammer nunca usa la historia**: lo único que hace con un repo es `git archive <commit> |
176tar -x`, o sea materializar un árbol.
177
178### El detalle que costó encontrar: el fichero `shallow`
179
180Un bundle hecho desde un repo shallow **no lleva la frontera de historia**. Al desempaquetarlo:
181
182```text
183fatal: Failed to traverse parents of commit 4f41128…
184error: … did not send all necessary objects
185```
186
187El mensaje dice «no envió todos los objetos necesarios» y **es engañoso**: los objetos del commit
188llegan enteros — de hecho `git archive` ya funciona pese al error. Lo que falta no es un objeto, es
189decirle a git dónde termina la historia. Se arregla escribiendo el propio commit en
190`<destino>/shallow` **antes** del fetch, y no hay que transportar nada: la frontera de un clon
191`--depth 1` es exactamente ese commit.
192
193### Y un bug propio que vale documentar
194
195`hidratar_desde_bundle` pasaba al `git fetch` la ruta **relativa** del bundle. Como `run_git` invoca
196`git -C <destino> …`, git la resolvía **dentro de `<destino>`** y no encontraba nada. Como el fallo
197del mirror se traga a propósito (para caer a upstream), el síntoma salía lejísimos del origen: el
198build moría con *«commit … no existe en \<repo\> tras fetch»*, **culpando a upstream de un error de
199ruta local**. Se arregla con `canonicalize`. Es el precio de que el mirror falle en silencio, y por
200eso el silencio se paga con comentarios explícitos en el código.
201
202## Lo que este ADR NO decide
203
204- Qué hacer con la concentración en GitHub.
205- Si el mirror debe replicarse fuera de Hetzner (hoy el repo, el respaldo y el mirror están todos en
206  la misma cuenta y el mismo proveedor).
207- El **coste de mantener el mirror git al día**: un commit nuevo en una receta es un bundle nuevo, y
208  hoy eso lo dispara una persona corriendo `mirror-git-poblar.sh`, no el latido.
209- Qué hacer con los repos cuyo servidor **no permite fetch por SHA suelto**
210  (`uploadpack.allowReachableSHA1InWant` desactivado): ahí el `--depth 1` del commit exacto falla y
211  hay que caer a un clon completo. **Todavía no ha aparecido ninguno.**
212
213  El poblador reporta el **stderr real de git**, no una conjetura. Lo escribí al revés la primera
214  vez — imprimía siempre `✗ upstream no da el commit` — y en la primera tanda marcó así a tres
215  recetas (`diffutils`, `findutils-xargs`, `kustomize`) cuyos commits **sí se traen a mano**. En
216  cuanto imprimió el error de verdad, la causa resultó ser otra por completo: el pin de esas tres no
217  es un commit (§ siguiente). Un fallo ahí puede ser el servidor negando el sha, pero también un
218  timeout, DNS, un rate-limit o —como fue— un bug propio, y cada uno se arregla distinto. **Un
219  diagnóstico hardcodeado convierte cualquier fallo en una conclusión falsa sobre upstream**, que es
220  el mismo error que ya costó caro con la ruta relativa del bundle.
221
222## El pin de una receta no siempre es un commit
223
224`diffutils`, `findutils-xargs` y `kustomize` pinean en su campo `commit` el SHA de un **objeto tag
225anotado** (`v0.5.0`, `0.9.1`, `kustomize/v5.8.1`), no de un commit. Es legítimo: `git archive` acepta
226un tag igual que un commit, y para `hash_inputs` un SHA es un SHA — `git:{commit}` no distingue el
227tipo de objeto y no tiene por qué. Pero rompía las dos puntas del mirror, y en las dos por la misma
228suposición sin escribir:
229
230- **El poblador** hacía `update-ref refs/heads/hammer <sha>`, y una rama sólo apunta a commits:
231  *«trying to write non-commit object»*. Ahora pela con `<sha>^{commit}` para la rama y, si hubo que
232  pelar, manda el objeto tag aparte en `refs/tags/hammer-objeto`. Sin ese segundo ref el bundle
233  desempaqueta bien pero el `cat-file -e <commit>` del otro lado no encuentra lo que la receta pide:
234  un mirror **correcto pero inútil justo para esas recetas**.
235- **hammer** escribía el `commit` de la receta en el fichero `shallow`, que sólo admite SHAs de
236  commit. Ya no lo supone: lee la frontera del propio bundle con `git bundle list-heads`, que imprime
237  la lista de refs **sin necesitar los objetos** y por eso sirve justo antes del fetch. Y trae
238  `refs/*:refs/*` en vez de un ref concreto, para que el objeto tag viaje con lo demás.
239
240Los bundles del formato viejo (un solo ref, los 339 ya subidos) siguen sirviendo sin tocarlos: para
241ellos `list-heads` devuelve el commit y el refspec ancho encuentra ese mismo ref único. Comprobado
242con una receta de cada forma contra un `repo` que no resuelve por DNS, para que el mirror sea la
243única fuente posible.