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. Doconut divide essa tarefa em duas metades explícitas — um lado de escrita que publica os artefatos de um documento no armazenamento compartilhado, e um lado de leitura que os serve de qualquer nó.

Um único nó não precisa de nada disso: o caminho normal OpenDocumentAsync mantém o documento na memória desse nó e o vincula à sessão do navegador (veja Sessões e Segurança). Use esta página quando as solicitações de página podem chegar a um nó que nunca viu a abertura.

Como as duas metades se encaixam

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.

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á gravando; 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.

Lado de leitura — servir a partir do compartilhamento

Monte o manipulador FileShare no ramo que o cliente chama — /doconut, correspondendo a BasePath: 'doconut' — atrás da verificação de ticket:

csharp
var app = builder.Build();

app.UseDoconutResources();
app.Map("/doconut", branch =>
{
    branch.UseDoconutDistributedDocumentSecurity();   // bilhetes assinados — veja abaixo
    branch.UseDoconutCloud<FileShareCloudHandler>(options =>
    {
        options.Location          = CloudLocation.FileShare;
        options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
    }, "/");
});

UseDoconutCloud recebe o provedor como seu argumento de tipo. 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 todo o documento antes de retornar. Para retornar assim que o token é 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 solicitaçã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 em vez 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 sendo renderizadas. Aplica‑se apenas à publicação em segundo plano em pastas por token (UsePerTokenSubfolders = true); o PublishAsync síncrono a ignora, pois seu chamador espera todo o documento 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:   'doconut',
    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 sendo renderizadas. O orçamento de tentativas e seus padrões (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs) estão documentados em ConfiguraçãoDoVisualizador.

Segurança entre nós

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 componentes trabalham juntos.

1. Registrar a segurança dos 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 cada nó
    .SetApplicationName("doconut-farm");

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

2. Verificar tickets no lado de leitura. UseDoconutDistributedDocumentSecurity() vai na ramificação de leitura antes de UseDoconutCloud, como no exemplo do lado de leitura.

3. Emitir um ticket quando o documento é aberto. O ticket nomeia 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 lado de leitura 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 para o widget. O visualizador envia o ticket como access em cada solicitaçã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 solicitaçã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 mantenha cookies.

Nunca leve UnsafeMode = true de volta para uma implantação de nó único, e nunca o trate como um 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.

Checklist

  1. Construa o FileShareConfig em um helper, registre‑o uma vez e use‑o em ambas as metades.
  2. Aponte o RootPath para uma pasta que todo nó possa alcançar.
  3. Publique com PublishAsync(...), ou EnqueueAsync(...) com publicação em segundo plano.
  4. Sirva com UseDoconutCloud<FileShareCloudHandler>(...) no branch que o cliente chama.
  5. Com publicação em segundo plano, habilite 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 branch 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?