Despliegues Distribuidos

Sirva 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. Doconut 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.

Un solo nodo no necesita nada de esto: la ruta normal OpenDocumentAsync mantiene el documento en la memoria de ese nodo y lo vincula a la sesión del navegador (ver Sesiones y Seguridad). Use esta página cuando las solicitudes de página pueden llegar a un nodo que nunca vio la apertura.

Cómo encajan las dos mitades

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 manejador de lectura sirve con uno. Si RootPath o UsePerTokenSubfolders difieren entre sí, el otro nodo responde 404. Construya la configuración en un solo lugar y regístrela 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.

FileShareConfig vive en Doconut.Clouds, junto con AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig y FTPConfig.

PropiedadPropósito
LocationCloudLocation.FileShare para un recurso UNC/local
RootPathLa carpeta compartida a la que puede acceder cualquier nodo
UsePerTokenSubfoldersMantenga los artefactos de cada documento en su propia carpeta {token} (por defecto 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 valor por defecto) verifica una vez. No tiene efecto en los documentos publicados de forma sincrónica

Lado de escritura — publicar el documento

Inyecte DistributedDocumentPublisher y publique 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 endpoint también devuelve un ticket de acceso firmado — vea Seguridad entre nodos.

Lado de lectura — servir desde el recurso compartido

Montar el controlador FileShare en la rama que llama el cliente — /doconut, coincidiendo con BasePath: 'doconut' — detrás de la verificación del ticket:

csharp
var app = builder.Build();

app.UseDoconutResources();
app.Map("/doconut", branch =>
{
    branch.UseDoconutDistributedDocumentSecurity();   // tickets firmados — ver abajo
    branch.UseDoconutCloud<FileShareCloudHandler>(options =>
    {
        options.Location          = CloudLocation.FileShare;
        options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
    }, "/");
});

UseDoconutCloud toma el proveedor como su argumento de tipo. 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 nada.

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 opt‑in 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 la ignora.) La cola está limitada: cuando se satura, 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 se han escrito: 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. Sólo 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 la reintento en el widget:

javascript
const objViewer = $('#div_ctlDoc').docViewer({
    BasePath:   'doconut',
    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 reintento y sus valores predeterminados (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs) están documentados en ConfiguraciónDelVisor.

Seguridad entre nodos

Los tokens vinculados a la sesión asumen que el nodo que sirve vio la solicitud de apertura. 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 aplica. Reemplácelo con tickets de acceso firmados, que cada nodo puede verificar de forma independiente. Cuatro piezas trabajan juntas.

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 a través de 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, 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.

Cerrar un documento publicado

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

text
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)

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

Lista de verificación

  1. Construye el FileShareConfig en un único ayudante, regístralo una vez y úsalo desde ambas mitades.
  2. Apunta RootPath a una carpeta a la que cada nodo pueda acceder.
  3. Publica con PublishAsync(...), o EnqueueAsync(...) con publicación en segundo plano.
  4. Sirve con UseDoconutCloud<FileShareCloudHandler>(...) en la rama que el cliente solicita.
  5. Con publicación en segundo plano, activa FirstPagePriority y retryOn409 juntos, y otorga 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 de Protección de Datos 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?