Despliegues Distribuidos

Sirve un documento desde varios nodos

Cuando varios nodos sirven los mismos documentos, el nodo que renderiza un documento no es necesariamente el nodo que responde a las solicitudes de página del navegador. Esta versión divide esa tarea en dos mitades explícitas — un lado de escritura que publica los artefactos de un documento en almacenamiento compartido, y un lado de lectura que los sirve desde cualquier nodo.

Si tu aplicación actualmente llama a UseDoconutWebFarm(...), esta página es tu reemplazo. Ni UseDoconutWebFarm ni WebFarmOptions existen en esta versión.

Tu topología no cambia. Apunta la raíz compartida al mismo camino UNC que usas hoy y cada nodo seguirá funcionando como lo hace ahora. Lo que cambia es que la publicación es una operación que llamas, en lugar de un efecto secundario de la renderización.

Qué reemplazó al middleware web-farm

Anteriormente un middleware hacía todo: servía imágenes pre‑renderizadas desde una carpeta compartida y encuestaba mientras otro nodo todavía las escribía. La espera era un presupuesto ciego — "bloquear hasta tres minutos esperando que la página aparezca".

Ahora el mismo trabajo son dos llamadas que puedes ver y razonar:

text
node A            open request
                      -> PublishAsync(...)   writes pages, document info,
                                             search index and metadata
                                             into  RootPath/{token}/
                      -> returns the token

node B            ?token=...&page=7
                      -> UseDoconutCloud<FileShareCloudHandler>
                      -> reads RootPath/{token}/ and serves the page

La configuración compartida que ambas mitades necesitan

El publicador escribe con un FileShareConfig y el controlador de lectura sirve con uno. Si RootPath o UsePerTokenSubfolders difieren entre ellos, el otro nodo responde 404. Construye la configuración en un solo lugar y regístrala una vez, de modo que ambas mitades lean el mismo objeto:

csharp
var rootPath = builder.Configuration["Doconut:SharedRoot"]!;   // p. ej. \\fileserver\doconut
builder.Services.AddSingleton(SharedStore.Config(rootPath, asyncPublish: false));

internal static class SharedStore
{
    public static FileShareConfig Config(string rootPath, bool asyncPublish) => new()
    {
        Location              = CloudLocation.FileShare,
        RootPath              = rootPath,
        UsePerTokenSubfolders = true,
        ReadReadyPollMs       = asyncPublish ? 250 : 0,
    };
}

Pase asyncPublish: true cuando active la publicación en segundo plano(publicación en segundo plano).

FileShareConfig vive en Doconut.Clouds, junto con AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig y FTPConfig. En la biblioteca anterior estos estaban en Doconut.Configs.Cloud; los nombres de clase no cambiaron.

PropiedadPropósito
LocationCloudLocation.FileShare para un recurso compartido UNC/local
RootPathLa carpeta compartida a la que puede acceder cualquier nodo
UsePerTokenSubfoldersMantenga los artefactos de cada documento en su propia carpeta {token} (predeterminado true)
ReadReadyPollMsCuánto tiempo espera el lado de lectura por una página que una publicación en segundo plano aún está escribiendo; 0 (el predeterminado) verifica una vez. No tiene efecto en los documentos publicados de forma sincrónica

Lado de escritura — publicar el documento

Inyecta DistributedDocumentPublisher y publica en lugar de abrir una sesión local. Una llamada renderiza y escribe el conjunto completo de artefactos — páginas, información del documento, índice de búsqueda y metadatos — y devuelve cuando ha terminado:

csharp
app.MapPost("/api/open", async (string fileName, FileShareConfig shareConfig,
    DistributedDocumentPublisher publisher, CancellationToken ct) =>
{
    var path            = Path.Combine("files", Path.GetFileName(fileName));
    var config          = new PdfConfig { AllowSearch = true };
    var documentOptions = new DocOptions { TimeOut = 60 };
    var publishOptions  = new DistributedDocumentPublishOptions { CleanUpStagingDirectory = true };

    DistributedDocumentPublishResult result = await publisher.PublishAsync(
        path, shareConfig, config, documentOptions, publishOptions, ct);

    return Results.Text(result.Token);
});

DistributedDocumentPublishResult lleva Token, ArtifactPath, TotalPages y Format. El token se envía al navegador exactamente como lo hace un token de visor normal. En una granja, el punto final también devuelve un ticket de acceso firmado — vea Seguridad entre nodos(Seguridad entre nodos).

Esta única llamada reemplaza al par anterior — abrir el documento en una sesión local y luego volcar imágenes en el recurso compartido con ExportToPng(sharedPath). ExportToPng y ExportToCloud no tienen equivalente aquí.

Lado de lectura — servir desde el recurso compartido

Monte el controlador FileShare en la misma rama que el cliente ya llama, detrás de la verificación del ticket:

csharp
var app = builder.Build();

app.UseDoconutResources();
app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch =>
    {
        branch.UseDoconutDistributedDocumentSecurity();   // tickets firmados — ver abajo
        branch.UseDoconutCloud<FileShareCloudHandler>(options =>
        {
            options.Location          = CloudLocation.FileShare;
            options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
        }, "/");
    });

UseDoconutCloud es genérico en esta versión: el proveedor es el argumento de tipo en lugar de un valor Location conmutado dentro del middleware. Los controladores se nombran <Provider>CloudHandler — FileShareCloudHandler, AzureCloudHandler, AmazonS3CloudHandler, GoogleCloudHandler, DropBoxCloudHandler, RedisCloudHandler, FTPCloudHandler y CDNCloudHandler. Con el prefijo de ruta "/", el controlador responde a cada solicitud que llega a su rama.

El controlador CDN es solo lectura — sirve lo que ya está en el CDN; no sube.

Opcional: publicar en segundo plano

Por defecto PublishAsync renderiza todo el documento antes de devolverlo. Para devolver tan pronto como el token se genera y permitir que un trabajador alojado renderice en la misma carpeta, registre la cola de opción y construya la configuración compartida con asyncPublish: true:

csharp
builder.Services.AddDoconut(options => { /* … */ });
builder.Services.AddDoconutDistributedAsyncPublish();

Sin este registro no se registra nada y la publicación permanece sincrónica, exactamente como antes.

Luego llame a EnqueueAsync en lugar de PublishAsync. (DistributedDocumentPublishOptions.Async es solo una bandera que su propio código puede leer para elegir entre los dos caminos; el publicador lo ignora.) La cola es limitada: cuando está saturada, EnqueueAsync lanza DistributedPublishQueueFullException. Responda con un 503 y una cabecera Retry-After para que los clientes retrocedan en lugar de bloquearse:

csharp
app.MapPost("/api/open", async (string fileName, FileShareConfig shareConfig,
    IDistributedPublishQueue publishQueue, HttpResponse response, CancellationToken ct) =>
{
    var path            = Path.Combine("files", Path.GetFileName(fileName));
    var config          = new PdfConfig { AllowSearch = true };
    var documentOptions = new DocOptions { TimeOut = 60 };
    var publishOptions  = new DistributedDocumentPublishOptions { FirstPagePriority = true };

    try
    {
        var token = await publishQueue.EnqueueAsync(
            path, shareConfig, config, documentOptions, publishOptions, ct);
        return Results.Text(token);
    }
    catch (DistributedPublishQueueFullException)
    {
        response.Headers["Retry-After"] = "5";
        return Results.StatusCode(503);
    }
});

Páginas que aún no están escritas: HTTP 202

Con la publicación en segundo plano, una solicitud de página puede llegar antes de que el trabajador haya escrito esa página. El lado de lectura espera hasta ReadReadyPollMs y luego responde HTTP 202 Accepted en lugar de bloquear la solicitud.

FirstPagePriority = true acorta la espera para la primera vista: la página 1 se escribe primero en la carpeta del documento, de modo que el documento se abre mientras las páginas posteriores siguen renderizándose. Solo se aplica a la publicación en segundo plano en carpetas por token (UsePerTokenSubfolders = true); el PublishAsync sincrónico lo ignora, porque su llamador espera todo el documento de todos modos.

Eso traslada la espera al cliente, donde está limitada y es visible. Habilite reintentos en el widget:

javascript
const objViewer = $('#div_ctlDoc').docViewer({
    BasePath:   '/',
    ResPath:    'doconut-res/images',
    retryOn409: true      // reintentos 202 (y legado 409) respuestas de disponibilidad
});

Un cliente que no reintenta muestra mosaicos rotos para las páginas que aún se están renderizando. El presupuesto de reintentos y sus valores predeterminados (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs) están documentados en ConfiguraciónDelVisor.

Este par — publicación en segundo plano con FirstPagePriority, más la encuesta del lado de lectura — es lo que reemplaza las configuraciones anteriores PageWaitTimeSeconds y StartWaitFromPage. Ninguna de ellas existe ya.

Seguridad entre nodos

Los tokens vinculados a la sesión asumen que el nodo que sirve vio la solicitud inicial. En una granja no lo hizo, por lo que la verificación por sesión rechazaría solicitudes legítimas; una granja por lo tanto establece UnsafeMode = true.

UnsafeMode = true no es el modelo de seguridad — es la eliminación de uno que ya no se aplica.
Reemplácelo con tickets de acceso firmados, que cada nodo puede verificar de forma independiente. Cuatro componentes trabajan juntos.

1. Registrar la seguridad de tickets en cada nodo.
Los tickets están protegidos con ASP.NET Core Data Protection, por lo que cada nodo debe usar el mismo anillo de claves y nombre de aplicación; un nodo con claves diferentes no puede leer un ticket emitido por otro nodo.

csharp
using Microsoft.AspNetCore.DataProtection;

builder.Services.AddDataProtection()
    .PersistKeysToFileSystem(new DirectoryInfo(@"\\fileserver\doconut-keys"))   // compartido por cada nodo
    .SetApplicationName("doconut-farm");

builder.Services.AddDoconut(options => options.UnsafeMode = true);
builder.Services.AddDoconutDistributedDocumentSecurity(options =>
{
    options.TicketLifetimeMinutes = 60;   // el predeterminado
});

2. Verificar los tickets en el lado de lectura.
UseDoconutDistributedDocumentSecurity() se coloca en la rama de lectura antes de UseDoconutCloud, como en el ejemplo del lado de lectura.

3. Emitir un ticket cuando se abre el documento.
El ticket nombra el token, el navegador (a través de una cookie que el lado de lectura compara), y el usuario autenticado, si lo hay:

csharp
using System.Security.Claims;
using Microsoft.Extensions.Options;

app.MapPost("/api/open", async (string fileName, HttpContext http, FileShareConfig shareConfig,
    DistributedDocumentPublisher publisher, IDocumentAccessTicketProtector protector,
    IOptions<DistributedDocumentSecurityOptions> security, CancellationToken ct) =>
{
    var path   = Path.Combine("files", Path.GetFileName(fileName));
    var result = await publisher.PublishAsync(path, shareConfig, ct: ct);

    // Vincula el ticket a este navegador mediante la cookie que verifica el lado de lectura.
    var cookieName = security.Value.BrowserCookieName;   // "doconut-client" por defecto
    if (!http.Request.Cookies.TryGetValue(cookieName, out var browserId) || string.IsNullOrEmpty(browserId))
    {
        browserId = Guid.NewGuid().ToString("N");
        http.Response.Cookies.Append(cookieName, browserId, new CookieOptions
        {
            HttpOnly = true,
            Secure   = http.Request.IsHttps,
            SameSite = SameSiteMode.Lax
        });
    }

    var access = protector.Protect(new DocumentAccessTicket
    {
        Token      = result.Token,
        BrowserId  = browserId,
        UserId     = http.User.FindFirstValue(ClaimTypes.NameIdentifier) ?? "",
        ExpiresUtc = DateTimeOffset.UtcNow.AddMinutes(security.Value.TicketLifetimeMinutes),
        Nonce      = Guid.NewGuid().ToString("N")
    });

    return Results.Json(new { token = result.Token, access });
});

4. Pasar ambos al widget.
El visor envía el ticket como access con cada solicitud:

javascript
const resp = await fetch('/api/open?fileName=Sample.pdf', { method: 'POST' });
const { token, access } = await resp.json();
objViewer.View(token, access);

El lado de lectura rechaza una solicitud cuyo ticket falta, es inválido, fue emitido para otro token, está expirado, vinculado a otra cookie del navegador, o emitido a otro usuario autenticado. Responde 403 — con la imagen de error UnauthorizedMessage para solicitudes de página y miniatura, y como texto plano en caso contrario. Pruebe con un navegador real o un cliente que conserve cookies.

Nunca lleve UnsafeMode = true de vuelta a una implementación de un solo nodo, y nunca lo trate como un atajo para una verificación de sesión fallida en un nodo — allí la solución correcta es AddSession() / UseSession(). Vea Sesiones y Seguridad.

Cerrando un documento publicado

CloseDocument(token) en el Viewer inyectado elimina una sesión local. Para eliminar los artefactos publicados de un documento del recurso compartido, el publicador expone:

text
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)

Pase el mismo FileShareConfig con el que se publicó el documento.

Mapeo configuración por configuración

AnteriorAhora
UseDoconutWebFarm(new WebFarmOptions { … })PublishAsync(...) en el lado de escritura más UseDoconutCloud<FileShareCloudHandler>(...) en el lado de lectura
WebFarmOptions.PathFileShareConfig.RootPath
PageWaitTimeSeconds / StartWaitFromPagePublicación en segundo plano con DistributedDocumentPublishOptions.FirstPagePriority, más FileShareConfig.ReadReadyPollMs
viewer.OpenDocument(...) then viewer.ExportToPng(share)una llamada PublishAsync(...)
viewer.ExportToCloud(cloudConfig)PublishAsync(...) con la configuración del proveedor
UseDoconutCloud(new CloudOptions { Location = … })UseDoconutCloud<THandler>(options => …, pathPrefix)
DocOptions.IsWebfarm / WebfarmPathTodavía presente, escrito IsWebFarm / WebFarmPath — no necesario en la ruta de publicación
Doconut.Configs.CloudDoconut.Clouds

Lista de verificación

  1. Construye el FileShareConfig en un único ayudante, regístralo una vez y úsalo desde ambas mitades.
  2. Apunta RootPath al recurso compartido que ya utilizas.
  3. Publica con PublishAsync(...); elimina cualquier llamada ExportToPng / ExportToCloud.
  4. Sirve con UseDoconutCloud<FileShareCloudHandler>(...) en la rama que llama el cliente.
  5. Con la publicación en segundo plano, activa FirstPagePriority y retryOn409 juntos, y da al lado de lectura un ReadReadyPollMs distinto de cero.
  6. Reemplaza la verificación por sesión con tickets de acceso firmados — un anillo de claves Data Protection en cada nodo, UseDoconutDistributedDocumentSecurity() en la rama de lectura, un ticket del punto final abierto — y no envíes UnsafeMode = true solo.
  7. Verifica abriendo un documento en un nodo y solicitando una página tardía desde otro.

¿Fue útil esta página?