Refresco condicional de licencia con ETag
Un cliente de Keyright refresca su lease en caché con un temporizador, y la inmensa mayoría de esos refrescos responden la misma pregunta con la misma respuesta: nada cambió. Volver a descargar el lease firmado completo cada vez desperdicia ancho de banda y repite una verificación de firma sin motivo. HTTP ya tiene la herramienta adecuada para «¿ha cambiado este recurso desde la última vez que lo vi?»: el ETag y el GET condicional. Este artículo muestra cómo el servicio emisor etiqueta cada respuesta de licencia con un validador fuerte, cómo el SDK envía If-None-Match para convertir un refresco en un económico 304 Not Modified, y las reglas de corrección que impiden que un 304 oculte jamás una revocación.
Un cliente de Keyright no llama a casa en cada comprobación de licencia. Se activa una vez, cachea el lease firmado y, a partir de ahí, cada Validate() es una operación local y sin conexión contra la clave pública incrustada. Lo que sí habla con el servicio emisor es el refresco en segundo plano: con un temporizador —normalmente cada pocos minutos o pocas horas— el SDK vuelve a obtener el lease para que una renovación, un cambio de entitlement o una revocación se recojan sin esperar a un reinicio.
Esto es lo esencial de ese bucle de refresco: casi todas sus iteraciones son inocuas. Una licencia es un recurso que cambia despacio. Cambia cuando alguien renueva, actualiza, transfiere un asiento o es revocado: eventos que ocurren con días o semanas de diferencia. Entre esos eventos, un cliente que refresca cada cinco minutos pregunta al servicio «¿cuál es el estado actual de esta licencia?» cientos de veces y recibe de vuelta, byte a byte, el mismo lease firmado todas y cada una de las veces. Cada una de esas respuestas es un cuerpo completo que el servicio serializó y firmó, empujó por la red, y que el cliente luego decodificó en base64 y sobre el que ejecutó una verificación RSA: todo para confirmar lo que ya sabía.
HTTP tiene la primitiva adecuada para esto desde 1999. Es el GET condicional, construido sobre la cabecera de respuesta ETag y la cabecera de petición If-None-Match, y cablearlo en la ruta de refresco convierte el caso común —nada cambió— en un viaje de ida y vuelta solo de cabeceras que devuelve 304 Not Modified con un cuerpo vacío.
Idea clave: Haz que tu servicio emisor estampe cada respuesta de licencia con un ETag fuerte derivado de la versión y la firma de la licencia. Haz que el SDK recuerde esa etiqueta y la devuelva como If-None-Match en el siguiente refresco. Cuando nada ha cambiado, el servicio responde 304 Not Modified sin cuerpo, el cliente conserva intacto su lease en caché, y has sustituido una descarga completa de payload firmado más una verificación de firma por unos cientos de bytes de cabeceras, sin dejar jamás que una caché obsoleta oculte una revocación.
Cómo es hoy la obtención de una licencia
Quita el SDK y un refresco es un GET HTTP ordinario. El cliente pide el lease actual para una clave; el servicio devuelve el documento firmado.
GET /v1/licenses/current HTTP/1.1
Host: keyright.example.com
X-Keyright-Product: acme-suite
Authorization: Bearer AK-9f3c… ← el token de activación del handshake inicial
HTTP/1.1 200 OK
Content-Type: application/vnd.keyright.lease+json
Content-Length: 1184
{ "lease": "eyJhbGciOi…", "signature": "MEUCIQ…", "edition": "pro", "expiresAt": "2027-01-01T00:00:00Z" }
Ese blob lease es el payload canónico y firmado que el cliente verifica sin conexión. A más de un kilobyte por vez, multiplicado por una flota de clientes, por un refresco cada pocos minutos, por el hecho de que el contenido es idéntico entre eventos de licencia, es puro desperdicio. El servicio hizo trabajo real para producir un cuerpo que nadie necesitaba.
El ETag: una huella que el cliente puede citar de vuelta
Un ETag («entity tag») es un validador opaco que el servidor adjunta a una respuesta. Su único contrato es este: si dos respuestas para la misma URL llevan el mismo ETag, sus representaciones son idénticas; si el recurso cambia, el ETag debe cambiar. El cliente lo trata como una caja negra —nunca lo parsea— y simplemente lo cita de vuelta en la siguiente petición para preguntar «¿todavía tienes exactamente esto?».
Para una licencia no quieres hashear el cuerpo completo de la respuesta para producir la etiqueta (eso funciona, pero cuesta un hash sobre el payload en cada petición). Ya tienes dos campos que cambian si y solo si la licencia cambia: una versión monótona que el servicio emisor incrementa en cada mutación, y la firma en sí. Combínalos en un validador fuerte:
ETag: "v47-3b9a1f" ← versión 47 de la licencia, primeros bytes de la firma, etiqueta fuerte
Este es un ETag fuerte (sin prefijo W/), que es la elección correcta aquí: una petición condicional debería coincidir solo cuando los bytes son genuinamente idénticos, porque el cliente va a saltarse la verificación de una nueva firma en una coincidencia. Una etiqueta débil (W/"…"), que solo promete equivalencia semántica, es incorrecta para esto: «semánticamente equivalente» no es suficiente cuando la diferencia podría ser una revocación.
El servicio calcula la etiqueta a partir de campos que ya tiene a mano, así que etiquetar una respuesta es esencialmente gratis, y, de forma crucial, la etiqueta cambia en el instante en que lo hace cualquier cosa de la licencia: una renovación incrementa la versión, una revocación incrementa la versión, una edición de entitlement incrementa la versión.
El GET condicional: If-None-Match convierte un refresco en un 304
Una vez que el cliente ha visto un ETag, el siguiente refresco lo envía en una cabecera If-None-Match. La semántica es precisa: «devuelve el recurso completo solo si su ETag actual no coincide con ninguno de estos; de lo contrario, dime que no ha cambiado».
GET /v1/licenses/current HTTP/1.1
Host: keyright.example.com
X-Keyright-Product: acme-suite
Authorization: Bearer AK-9f3c…
If-None-Match: "v47-3b9a1f" ← ya tengo exactamente esto; ¿tú también?
HTTP/1.1 304 Not Modified
ETag: "v47-3b9a1f"
Cache-Control: max-age=300
Sin cuerpo. El cliente lee el 304, entiende «mi lease en caché sigue vigente», reinicia su temporizador de refresco y no hace nada más: sin decodificación, sin verificación de firma, sin cambio de estado. Cuando la licencia sí ha cambiado, la coincidencia falla y el servicio responde exactamente como antes, con un 200, el nuevo cuerpo y un nuevo ETag que el cliente almacena para la próxima vez.
Implementar el refresco condicional en el cliente del SDK
Si consumes el cliente de Keyright a través del registro de typed-client, las peticiones condicionales son algo que añades en la ruta de refresco: el SDK almacena el último ETag junto al lease en caché y lo envía en el siguiente sondeo. Esta es la forma de ese handler, escrito contra HttpClient para que la mecánica quede explícita.
public sealed class ConditionalLeaseFetcher(HttpClient http)
{
// El validador que el servicio nos dio por última vez, guardado junto al lease en caché.
private string? _etag;
private SignedLease? _cached;
public async Task<RefreshResult> RefreshAsync(CancellationToken ct)
{
using var req = new HttpRequestMessage(HttpMethod.Get, "/v1/licenses/current");
// Cita de vuelta la etiqueta almacenada. EntityTagHeaderValue parsea la forma entrecomillada.
if (_etag is not null)
req.Headers.IfNoneMatch.Add(EntityTagHeaderValue.Parse(_etag));
using var res = await http.SendAsync(req, HttpCompletionOption.ResponseHeadersRead, ct);
if (res.StatusCode == HttpStatusCode.NotModified)
{
// El caso común: el cuerpo está vacío por especificación. Conserva lo que tenemos, intacto.
return RefreshResult.Unchanged(_cached!);
}
res.EnsureSuccessStatusCode();
// 200: una representación genuinamente nueva. Solo ahora pagamos la decodificación + verificación.
var body = await res.Content.ReadFromJsonAsync<LeaseResponse>(ct)
?? throw new KeyrightException("empty lease body");
var lease = SignedLease.VerifyAndParse(body, _publicKey); // la verificación RSA ocurre aquí
_cached = lease;
_etag = res.Headers.ETag?.ToString(); // almacena el nuevo validador para la próxima vez
return RefreshResult.Updated(lease);
}
}
Las dos ramas son todo el quid. Un 304 devuelve RefreshResult.Unchanged y nunca toca la ruta de firma: lo más caro que puede hacer un refresco es justo lo único que la ruta rápida se salta. Un 200 se trata exactamente como lo haría una obtención sin caché: verificar, intercambiar la caché, almacenar el ETag fresco. No hay un tercer estado que equivocar.
Fíjate en HttpCompletionOption.ResponseHeadersRead: en un 304 no hay cuerpo que almacenar en búfer, así que quieres inspeccionar el estado a partir de las cabeceras antes de decidir si leer contenido en absoluto.
No dejes que max-age sustituya a la evaluación local
El Cache-Control: max-age=300 de la respuesta le dice al cliente que puede servir el lease en caché sin volver a preguntar durante hasta cinco minutos: eso es lo que fija el suelo de tu intervalo de refresco. Lo que no debe hacer es suprimir la parte local, dependiente del tiempo, de una comprobación de licencia. Un lease puede llevar un expiresAt que caiga dentro de la ventana de max-age; en el momento en que el reloj de pared lo supere, el entitlement desaparece aunque los bytes en caché sigan siendo «frescos» según la definición de HTTP. Esta es la misma división cubierta en el trabajo de caché de la ruta caliente: cachea la verificación de firma (el ETag protege eso), nunca caches la evaluación en el instante actual. Validate() siempre reevalúa la expiración contra el reloj validado, sin importar lo fresca que la caché HTTP crea que es la representación.
La regla de corrección que lo hace seguro
Una petición condicional es tan segura como la garantía de que el ETag cambia siempre que la licencia lo hace. Equivócate en eso y un 304 se convierte en una mentira: el cliente conserva un lease que el servicio ya revocó y sigue respondiendo 304 porque la etiqueta nunca se movió. Así que la regla del lado del servicio es absoluta:
Cualquier mutación que cambie lo que la licencia concede debe cambiar el ETag. Como la etiqueta se deriva de la versión monótona, y cada mutación incrementa la versión, esto sale gratis: una revocación incrementa la versión como cualquier otra edición, el siguiente If-None-Match no logra coincidir, y el cliente recibe un 200 que lleva el estado ahora revocado (que al verificarse resuelve al fallback de la Community Edition). No hay ruta en la que un cambio de licencia en vivo quede enmascarado por una etiqueta obsoleta, siempre que la versión sea la única fuente de verdad y la etiqueta sea fuerte, no débil.
El fallo inverso —que la etiqueta cambie cuando la licencia no lo hizo— es inofensivo. Solo significa un 200 innecesario de vez en cuando, el mismo coste que pagabas en cada petición antes. Las peticiones condicionales degradan hacia «descarga la cosa completa», nunca hacia «sirve algo obsoleto».
Probarlo con curl
Puedes observar todo el intercambio desde la línea de comandos, que es la forma más rápida de confirmar que tu servicio etiqueta correctamente antes de tocar el SDK. La primera obtención captura la etiqueta; la segunda la envía de vuelta.
$ curl -s -D - -H "Authorization: Bearer AK-9f3c…" \
https://keyright.example.com/v1/licenses/current -o /dev/null | grep -i etag
ETag: "v47-3b9a1f"
$ curl -s -D - -H "Authorization: Bearer AK-9f3c…" \
-H 'If-None-Match: "v47-3b9a1f"' \
https://keyright.example.com/v1/licenses/current -o /dev/null | head -1
HTTP/1.1 304 Not Modified
Un 304 en la segunda llamada prueba que el viaje de ida y vuelta funciona. Ahora fuerza un cambio —renueva la licencia, o incrementa su versión en tu arnés de pruebas— y repite la llamada condicional: deberías obtener un 200, un cuerpo nuevo y un ETag distinto. Si obtienes un 200 con el mismo ETag, tu etiqueta no se deriva de un campo que realmente cambió; si obtienes un 304 tras una revocación, tu ruta de revocación no está incrementando la versión, lo cual es un bug de corrección, no de caché.
Un escollo: proxies y eliminación de cabeceras
Si tus clientes alcanzan el servicio emisor a través de un proxy inverso o una CDN, confirma que reenvía If-None-Match aguas arriba y que no responde él mismo a la petición condicional desde una caché que desconoce la revocación. Una respuesta de licencia debería marcarse Cache-Control: private precisamente para que las cachés compartidas no la almacenen; la validación condicional pertenece entre el cliente y el servicio emisor, no en un intermediario que no tiene ni idea de que una licencia fue retirada. Mantén el validador de extremo a extremo y el 304 significará exactamente lo que crees que significa.
Ese es todo el mecanismo. El bucle de refresco sigue corriendo con su temporizador, sigue recogiendo cada renovación y revocación a tiempo, y sigue verificando cada lease genuinamente nuevo, pero el caso abrumadoramente común, «nada cambió desde la última vez que pregunté», ahora cuesta unos cientos de bytes de cabeceras y una lectura de la línea de estado en lugar de una descarga de payload firmado y una verificación con clave pública. La licencia no cambió, así que el cliente no hace el trabajo de fingir que podría haberlo hecho.
Prueba Nebula.NET
Endurece tu código .NET en minutos — empieza con la edición gratuita.