Despliegues Distribuidos

Servir 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). Utilice 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 cualquier nodo puede acceder
UsePerTokenSubfoldersMantener 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 predeterminado) 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 va 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 — ver Seguridad entre nodos.

Lado de lectura — servir desde el share

Monte 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 llaman <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 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. 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 reintentos 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 reintentos 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 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 los 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 para otro usuario autenticado. Responde con 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.

Cierre de 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. Construya el FileShareConfig en un ayudante, regístrelo una vez y úselo desde ambas mitades.
  2. Apunte RootPath a una carpeta a la que cada nodo pueda acceder.
  3. Publique con PublishAsync(...), o EnqueueAsync(...) con publicación en segundo plano.
  4. Sirva con UseDoconutCloud<FileShareCloudHandler>(...) en la rama que llama el cliente.
  5. Con publicación en segundo plano, active FirstPagePriority y retryOn409 juntos, y dé a la parte de lectura un ReadReadyPollMs distinto de cero.
  6. Reemplace 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íe UnsafeMode = true solo.
  7. Verifique abriendo un documento en un nodo y solicitando una página tardía desde otro.

¿Fue útil esta página?