Skip to content
← Todas las publicaciones
· Delta1 Labs LicensingKeyright

Ventanas de gracia para una caída transitoria del servidor de licencias

Una comprobación de licencia en línea que falla en seco en cuanto tu servicio emisor de Keyright está brevemente inalcanzable convierte un parpadeo de DNS o un despliegue rutinario en una caída que ven tus clientes. Este artículo muestra cómo capear caídas transitorias con una ventana de gracia configurable sobre un resultado de validación firmado y en caché: distinguiendo «servicio inalcanzable» (transitorio, sigue funcionando) de «licencia revocada» (definitivo, falla cerrado ya), acotando la gracia con las marcas de tiempo firmadas por el propio servicio para que nadie la alargue desconectando la red, registrando cada ejecución en caché y fallando cerrado de forma limpia cuando se agota la ventana.

Una comprobación de licencia en línea te da cosas que una offline no puede: recuentos de asientos en vivo, revocación instantánea, medición de uso. Pero trae consigo un modo de fallo que es fácil introducir sin querer. Si tu código trata cada fallo al alcanzar el servicio emisor como una validación fallida, entonces la primera vez que tu instancia autoalojada de Keyright esté brevemente inalcanzable — un parpadeo de DNS, un despliegue progresivo, un proxy que corta una conexión — todos los clientes que pagan quedan bloqueados a la vez. Un evento de infraestructura de treinta segundos se convierte en una caída de treinta segundos de cara al cliente, y a los tickets de soporte no les importa que la licencia fuera válida todo el tiempo.

La solución no es dejar de comprobar en línea. Es dejar de confundir «el servicio dijo que no» con «no pude alcanzar el servicio», y capear el segundo caso con un resultado firmado y en caché durante una ventana de gracia acotada.

Idea clave: Guarda en caché la última validación correcta de forma local, firmada para que no se pueda falsificar. Cuando el servicio esté inalcanzable, sigue honrando el resultado en caché durante una ventana de gracia configurable acotada por las propias marcas de tiempo firmadas del servicio (para que nadie la alargue desconectando). Cuando el servicio esté alcanzable y diga que la licencia está revocada o caducada, falla cerrado de inmediato. Registra cada ejecución en caché y falla cerrado de forma limpia cuando se agote la ventana.

Los dos fallos que no deben parecerse

Cada revalidación en línea termina en uno de tres lugares, y todo el diseño gira en torno a mantenerlos separados.

  • Confirmado. El servicio respondió y la licencia está bien. Renueva el lease en caché y sigue.
  • No definitivo. El servicio respondió y la respuesta es revocada, caducada o asiento retirado. Esto es definitivo. Debes fallar cerrado ya — la gracia no aplica, porque la licencia de verdad ya no es válida.
  • Inalcanzable. El servicio no respondió en absoluto: un tiempo de espera de conexión, un fallo de DNS, un 502 de un proxy inverso en pleno despliegue. No aprendiste nada sobre la licencia. Lo último que te dijo el servicio sigue en pie, así que lo sigues honrando — por un tiempo.

El error es fusionar el segundo y el tercer caso en una sola rama de «validación fallida». Una revocación y una conexión TCP cortada son hechos opuestos. Uno significa que el cliente debe parar; el otro significa que tu red tuvo un hipo y el cliente no debería notarlo.

tiempoconfirmaciones en líneaúltima firmadaConfirmedAtUtccaída — la ventana de gracia cuenta atrásempieza la caídala licencia válida en caché sigue funcionando(acotada por marca firmada + MaxOfflineDuration)el servicio vuelve → reinicio…o si nunca vuelve:falla cerrado

Configurar la ventana de gracia

La gracia se configura una sola vez, donde inicializas el cliente. GracePeriod es cuánto tiempo sigue funcionando una licencia válida en caché tras la última confirmación correcta mientras el servicio está inalcanzable. MaxOfflineDuration es el techo absoluto de cuánto tiempo se honra jamás un lease en caché, sin importar cuántas veces se reiniciaría la gracia — es tu red de seguridad frente a una máquina que se desconecta y no vuelve.

static readonly KeyrightClient License = KeyrightClient.Initialize(new KeyrightOptions
{
    Product           = "acme-suite",
    PublicKeyBase64   = "MIIBIjANBgkq...",                   // ships in your binary; not a secret
    ServiceUrl        = "https://keyright.example.com",      // your self-hosted instance
    GracePeriod       = TimeSpan.FromHours(72),              // ride out outages this long after last contact
    MaxOfflineDuration = TimeSpan.FromDays(14),              // absolute ceiling on cached operation
});

Elige GracePeriod para superar con holgura tu peor evento transitorio realista — un despliegue largo, una rotación de certificados, un parpadeo de red regional — pero no tan largo que un cliente genuinamente cancelado funcione durante semanas. Setenta y dos horas cubren un incidente de un viernes por la tarde que nadie mira hasta el lunes. MaxOfflineDuration es el límite más largo y grueso; ajústalo a tu ciclo de facturación para que una máquina que nunca llama a casa acabe teniendo que hacerlo.

Refrescar: donde vive la separación transitorio-vs-definitivo

Validate() sigue siendo exactamente lo que siempre ha sido: una comprobación pura y offline del lease en caché contra tu clave pública embebida, que nunca lanza excepciones ni toca la red. El trabajo en línea ocurre en RefreshAsync, y su resultado es donde distingues los dos fallos.

RefreshResult refresh = await License.RefreshAsync(ct);

switch (refresh.Status)
{
    case RefreshStatus.Confirmed:
        // Service reachable, license good. SDK has already renewed the signed
        // cached lease (new ConfirmedAtUtc), so the grace window resets.
        break;

    case RefreshStatus.Revoked:
    case RefreshStatus.Expired:
    case RefreshStatus.SeatWithdrawn:
        // Service reachable and said no. Definitive — DO NOT enter grace.
        GateApplication(refresh.Reason);
        break;

    case RefreshStatus.ServiceUnreachable:
        // We learned nothing. The cached lease still stands within its grace window.
        _log.LogWarning("Keyright unreachable ({Detail}); running on cached validation.",
            refresh.Detail);
        break;
}

Si prefieres excepciones en una ruta de más bajo nivel, el fallo de conectividad aflora como una excepción tipada que puedes capturar, mientras que un rechazo definitivo no — vuelve como un resultado que debes inspeccionar:

try
{
    await License.RefreshAsync(ct);   // throwOnUnreachable: true overload
}
catch (KeyrightServiceUnreachableException ex)
{
    // Transient only: DNS, connect timeout, 5xx from a proxy. Keep the cached lease.
    _log.LogWarning(ex, "Transient Keyright outage; grace window active.");
}

La regla que hay que retener: una KeyrightServiceUnreachableException (o RefreshStatus.ServiceUnreachable) es lo único que encamina hacia la gracia. Un resultado revocado o caducado nunca es un problema de conectividad, así que nunca recibe el beneficio de la duda.

No llamas a RefreshAsync en la ruta caliente. Ejecútalo con un temporizador — cada pocos minutos, o al reanudar la app — y deja que Validate() atienda cada decisión real de bloqueo desde el lease en caché entremedias.

Leer la validación en caché y su marca de tiempo firmada

Cuando Validate() responde desde la caché y no desde una confirmación fresca, LicenseInfo te lo dice, y lleva la marca de tiempo firmada que acota la ventana de gracia. Cada campo de aquí está cubierto por la firma del servicio sobre el lease, así que ninguno puede editarse en disco sin romper la verificación.

LicenseInfo info = License.Validate();

if (info.ValidationSource == ValidationSource.Cache)
{
    DateTimeOffset confirmedAt = info.Lease.ConfirmedAtUtc;   // signed by the service
    TimeSpan remaining         = info.GraceRemaining;         // how long cached operation is still allowed

    _log.LogInformation(
        "Running on cached license: last confirmed {ConfirmedAt:u}, grace remaining {Remaining}.",
        confirmedAt, remaining);

    if (remaining < TimeSpan.FromHours(6))
        ShowBanner($"License server unreachable. Reconnect within {remaining:hh\\:mm} to stay licensed.");
}

if (info.Edition == LicenseEdition.Community)
{
    // Grace exhausted (or never licensed): the SDK has already fallen back to
    // Community Edition. Gate the paid entitlements, cleanly.
    DisablePaidFeatures();
}

Fíjate en el destino del repliegue: cuando se agota la gracia, un despliegue autoalojado baja a Community Edition, no se cae. Los derechos de pago se leen como deshabilitados a través de las mismas llamadas IsEnabled / GetLimit que ya usas, así que fallar cerrado no es más que tu bloqueo de siempre haciendo su trabajo — sin ninguna ruta de código especial de «te hemos bloqueado».

Consideraciones de reloj: por qué no puedes hacer trampa a la gracia desconectando

El ataque obvio contra cualquier ventana de gracia offline es tirar de la red y atrasar el reloj para que la gracia nunca transcurra. Keyright cierra esto por dos frentes.

La gracia se mide desde un instante firmado, no uno local. La cuenta atrás corre desde Lease.ConfirmedAtUtc, que el servicio firmó cuando respondió por última vez. Un usuario puede cambiar el reloj de su máquina, pero no puede mover una marca de tiempo que está dentro de un payload firmado sin invalidar la firma — y una firma inválida falla cerrado de inmediato.

Un reloj atrasado se trata como manipulación. Junto a la marca de tiempo firmada, el SDK persiste un marcador monótono y la última hora de servidor firmada que ha visto. Si el reloj del sistema marca luego una hora anterior a ese máximo alcanzado — la firma de un atraso deliberado — el SDK deja de confiar en el reloj local y falla cerrado en vez de conceder una gracia abierta:

if (info.ClockStatus == ClockStatus.WentBackwards)
{
    // Wall clock is earlier than the last signed server time we recorded.
    // Treat as tamper: do not extend grace.
    GateApplication("System clock rolled back; reconnect to re-validate.");
}

MaxOfflineDuration es la red de seguridad final. Incluso si pasaran todas las comprobaciones de reloj, ningún lease en caché se honra pasado ConfirmedAtUtc + MaxOfflineDuration. Desconectar el cable compra exactamente GracePeriod, y a lo largo de caídas cortas repetidas compra como mucho MaxOfflineDuration en total — nunca para siempre.

Telemetría mientras se funciona con validación en caché

Funcionar con caché es un estado degradado, y quieres saber que está pasando antes de que te lo diga un cliente. Vale la pena emitir dos cosas. Primero, una línea de log estructurada cada vez que una decisión de bloqueo se atiende desde la caché en lugar de desde una confirmación fresca — exactamente la rama ValidationSource == Cache de arriba — llevando confirmedAt y remaining para que puedas ver cuánto se ha adentrado una flota en la ventana. Segundo, una métrica o señal de salud sobre la que puedas alertar: si una proporción significativa de instancias está en validación en caché a la vez, eso es tu servicio emisor teniendo un mal día, no un puñado de clientes individuales quedándose offline. Mantén la propia clave fuera de esos logs (redáctala a un prefijo) igual que lo harías en cualquier otro sitio.

Fallar cerrado, de forma limpia

Cuando la gracia por fin se agota — MaxOfflineDuration alcanzado, atraso de reloj detectado, o volvió una revocación definitiva en cuanto el servicio fue alcanzable — el estado final es el mismo y debería ser poco dramático. Validate() devuelve LicenseEdition.Community, los derechos de pago se leen deshabilitados y tu bloqueo existente reduce la app a su superficie gratuita. El cliente ve un mensaje claro y accionable («reconéctate para revalidar») en lugar de una traza de pila, y en cuanto el servicio vuelve a ser alcanzable un único RefreshAsync confirma la licencia y restaura la función completa sin reinstalar y sin reintroducir una clave.

Esa es toda la forma del asunto: una caída que causaste tú no debería costarle nada a tu cliente, una cancelación debería costarle sus funciones de pago pronto, y la diferencia entre ambas es una marca de tiempo firmada y una ventana acotada — nunca una conexión caída confundida con un veredicto.

Prueba Nebula.NET

Endurece tu código .NET en minutos — empieza con la edición gratuita.