Implantações Distribuídas

Sirva um documento a partir de vários nós

Quando vários nós servem os mesmos documentos, o nó que renderiza um documento não é necessariamente o nó que responde às solicitações de página do navegador. Esta versão divide essa tarefa em duas metades explícitas — um lado de escrita que publica os artefatos de um documento em armazenamento compartilhado, e um lado de leitura que os serve de qualquer nó.

Se sua aplicação atualmente chama UseDoconutWebFarm(...), esta página é sua substituição. Nem UseDoconutWebFarm nem WebFarmOptions existem nesta versão.

Sua topologia não muda. Aponte a raiz compartilhada para o mesmo caminho UNC que você usa hoje e cada nó continuará funcionando da mesma forma. O que muda é que a publicação é uma operação que você chama, em vez de um efeito colateral da renderização.

O que substituiu o middleware web-farm

Anteriormente, um único middleware fazia tudo: servia imagens pré-renderizadas de uma pasta compartilhada e consultava enquanto outro nó ainda as escrevia. A espera era um orçamento cego — "bloquear até três minutos na esperança de que a página apareça".

Agora a mesma tarefa são duas chamadas que você pode ver e raciocinar:

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

A configuração compartilhada que ambas as metades precisam

O publicador grava com um FileShareConfig e o manipulador de leitura serve com um. Se RootPath ou UsePerTokenSubfolders diferirem entre eles, o outro nó responde 404. Construa a configuração em exatamente um lugar e registre-a uma única vez, para que ambas as metades leiam o mesmo objeto:

csharp
var rootPath = builder.Configuration["Doconut:SharedRoot"]!;   // por exemplo \\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,
    };
}

Passe asyncPublish: true ao ativar a publicação em segundo plano.

FileShareConfig está em Doconut.Clouds, junto com AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig e FTPConfig. Na biblioteca anterior, esses estavam em Doconut.Configs.Cloud; os nomes das classes não mudaram.

PropriedadePropósito
LocationCloudLocation.FileShare para um compartilhamento UNC/local
RootPathA pasta compartilhada que todo nó pode acessar
UsePerTokenSubfoldersMantenha os artefatos de cada documento em sua própria pasta {token} (padrão true)
ReadReadyPollMsQuanto tempo o lado de leitura espera por uma página que uma publicação em segundo plano ainda está escrevendo; 0 (o padrão) verifica uma vez. Não tem efeito em documentos publicados de forma síncrona

Lado de escrita — publicar o documento

Injete DistributedDocumentPublisher e publique em vez de abrir uma sessão local. Uma chamada renderiza e grava o conjunto completo de artefatos — páginas, informações do documento, índice de busca e metadados — e retorna quando termina:

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 transporta Token, ArtifactPath, TotalPages e Format. O token vai para o navegador exatamente como um token de visualizador normal. Em um farm, o endpoint também retorna um ticket de acesso assinado — veja Segurança entre nós.

Esta única chamada substitui o par anterior — abrir o documento em uma sessão local e então despejar imagens na partilha com ExportToPng(sharedPath). ExportToPng e ExportToCloud não têm equivalente aqui.

Lado de leitura — servir a partir do compartilhamento

Monte o manipulador FileShare no mesmo ramo que o cliente já chama, atrás da verificação de 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 assinados — veja abaixo
        branch.UseDoconutCloud<FileShareCloudHandler>(options =>
        {
            options.Location          = CloudLocation.FileShare;
            options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
        }, "/");
    });

UseDoconutCloud é genérico nesta versão: o provedor é o argumento de tipo ao invés de um valor Location alternado dentro do middleware. Os manipuladores são nomeados <Provider>CloudHandler — FileShareCloudHandler, AzureCloudHandler, AmazonS3CloudHandler, GoogleCloudHandler, DropBoxCloudHandler, RedisCloudHandler, FTPCloudHandler e CDNCloudHandler. Com o prefixo de caminho "/", o manipulador responde a cada requisição que chega ao seu ramo.

O manipulador CDN é somente leitura — ele serve o que já está no CDN; não faz upload.

Opcional: publicar em segundo plano

Por padrão, PublishAsync renderiza o documento inteiro antes de retornar. Para retornar assim que o token for criado e permitir que um worker hospedado renderize na mesma pasta, registre a fila de opt-in e construa a configuração compartilhada com asyncPublish: true:

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

Sem esse registro nada é registrado e a publicação permanece síncrona, exatamente como antes.

Então chame EnqueueAsync em vez de PublishAsync. (DistributedDocumentPublishOptions.Async é apenas uma bandeira que seu próprio código pode ler para escolher entre os dois caminhos; o publicador a ignora.) A fila é limitada: quando está saturada, EnqueueAsync lança DistributedPublishQueueFullException. Responda com um 503 e um cabeçalho Retry-After para que os clientes recuem em vez de travar:

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 ainda não foram escritas: HTTP 202

Com publicação em segundo plano, uma requisição de página pode chegar antes que o worker tenha escrito essa página. O lado de leitura aguarda até ReadReadyPollMs e então responde HTTP 202 Accepted ao invés de bloquear a requisição.

FirstPagePriority = true encurta a espera para a primeira visualização: a página 1 é escrita na pasta do documento primeiro, então o documento abre enquanto as páginas posteriores ainda estão renderizando. Aplica‑se apenas à publicação em segundo plano em pastas por token (UsePerTokenSubfolders = true); o PublishAsync síncrono a ignora, porque seu chamador espera pelo documento inteiro de qualquer forma.

Isso transfere a espera para o cliente, onde ela é limitada e visível. Habilite a nova tentativa no widget:

javascript
const objViewer = $('#div_ctlDoc').docViewer({
    BasePath:   '/',
    ResPath:    'doconut-res/images',
    retryOn409: true      // tentativas 202 (e legado 409) respostas de prontidão
});

Um cliente que não tenta novamente mostra blocos quebrados para páginas que ainda estão renderizando. O orçamento de tentativas e seus padrões (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs) estão documentados em ConfiguraçãoDoVisualizador.

Este par — publicação em segundo plano com FirstPagePriority, mais a sondagem do lado de leitura — é o que substitui as configurações anteriores PageWaitTimeSeconds e StartWaitFromPage. Nenhuma delas existe mais.

Segurança entre nós

Os tokens vinculados à sessão assumem que o nó de serviço viu a solicitação de abertura. Em um farm, isso não ocorre, portanto a verificação por sessão rejeitaria solicitações legítimas; um farm, portanto, define UnsafeMode = true.

UnsafeMode = true não é o modelo de segurança — é a remoção de um que não se aplica mais. Substitua‑o por tickets de acesso assinados, que cada nó pode verificar independentemente. Quatro partes trabalham juntas.

1. Registrar a segurança de tickets em cada nó. Os tickets são protegidos com ASP.NET Core Data Protection, portanto cada nó deve usar o mesmo anel de chaves e nome de aplicação; um nó com chaves diferentes não pode ler um ticket emitido por outro nó.

csharp
using Microsoft.AspNetCore.DataProtection;

builder.Services.AddDataProtection()
    .PersistKeysToFileSystem(new DirectoryInfo(@"\\fileserver\doconut-keys"))   // compartilhado por todos os nós
    .SetApplicationName("doconut-farm");

builder.Services.AddDoconut(options => options.UnsafeMode = true);
builder.Services.AddDoconutDistributedDocumentSecurity(options =>
{
    options.TicketLifetimeMinutes = 60;   // padrão
});

2. Verificar tickets no lado de leitura. UseDoconutDistributedDocumentSecurity() vai no ramo de leitura antes de UseDoconutCloud, como no exemplo do lado de leitura.

3. Emitir um ticket quando o documento for aberto. O ticket identifica o token, o navegador (por meio de um cookie que o lado de leitura compara) e o usuário autenticado, se houver:

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);

    // Vincule o ticket a este navegador através do cookie que o read side verifica.
    var cookieName = security.Value.BrowserCookieName;   // "doconut-client" por padrão
    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. Passar ambos ao widget. O visualizador envia o ticket como access em cada requisição:

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

O lado de leitura recusa uma requisição cujo ticket está ausente, inválido, emitido para outro token, expirado, vinculado a outro cookie de navegador ou emitido para outro usuário autenticado. Ele responde 403 — com a imagem de erro UnauthorizedMessage para solicitações de página e miniatura, como texto simples nos demais casos. Teste com um navegador real ou um cliente que preserve cookies.

Nunca leve UnsafeMode = true de volta para uma implantação de nó único, e nunca o trate como atalho para uma verificação de sessão falha em um nó — lá a correção correta é AddSession() / UseSession(). Veja Sessões e Segurança.

Encerrando um documento publicado

CloseDocument(token) no Viewer injetado descarta uma sessão local. Para remover os artefatos publicados de um documento do compartilhamento, o publicador expõe:

text
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)

Passe o mesmo FileShareConfig com o qual o documento foi publicado.

Mapeamento configuração por configuração

AnteriorAgora
UseDoconutWebFarm(new WebFarmOptions { … })PublishAsync(...) no lado de escrita e UseDoconutCloud<FileShareCloudHandler>(...) no lado de leitura
WebFarmOptions.PathFileShareConfig.RootPath
PageWaitTimeSeconds / StartWaitFromPagePublicação em segundo plano com DistributedDocumentPublishOptions.FirstPagePriority, e FileShareConfig.ReadReadyPollMs
viewer.OpenDocument(...) então viewer.ExportToPng(share)uma chamada PublishAsync(...)
viewer.ExportToCloud(cloudConfig)PublishAsync(...) com a configuração do provedor
UseDoconutCloud(new CloudOptions { Location = … })UseDoconutCloud<THandler>(options => …, pathPrefix)
DocOptions.IsWebfarm / WebfarmPathAinda presente, escrito IsWebFarm / WebFarmPath — não é necessário no caminho de publicação
Doconut.Configs.CloudDoconut.Clouds

Lista de Verificação

  1. Construa o FileShareConfig em um único helper, registre‑o uma vez e use‑o em ambas as metades.
  2. Aponte RootPath para o compartilhamento que você já usa.
  3. Publique com PublishAsync(...); exclua quaisquer chamadas ExportToPng / ExportToCloud.
  4. Sirva com UseDoconutCloud<FileShareCloudHandler>(...) no ramo que o cliente chama.
  5. Com publicação em segundo plano, ative FirstPagePriority e retryOn409 juntos, e dê ao lado de leitura um ReadReadyPollMs não zero.
  6. Substitua a verificação por sessão por tickets de acesso assinados — um anel de chaves Data Protection em cada nó, UseDoconutDistributedDocumentSecurity() no ramo de leitura, um ticket do endpoint aberto — e não envie UnsafeMode = true sozinho.
  7. Verifique abrindo um documento em um nó e solicitando uma página tardia de outro.

Esta página foi útil?