Distribuzioni distribuite

Fornisci un documento da diversi nodi

Quando più nodi forniscono gli stessi documenti, il nodo che rende un documento non è necessariamente quello che risponde alle richieste di pagina del browser. Doconut divide questo compito in due metà esplicite — un lato di scrittura che pubblica gli artefatti di un documento nello storage condiviso, e un lato di lettura che li serve da qualsiasi nodo.

Un singolo nodo non ha bisogno di tutto ciò: il percorso normale OpenDocumentAsync mantiene il documento nella memoria di quel nodo e lo associa alla sessione del browser (vedi Sessioni e Sicurezza). Usa questa pagina quando le richieste di pagina possono arrivare su un nodo che non ha mai visto l'apertura.

Come si incastrano le due metà

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 configurazione condivisa di cui entrambe le metà hanno bisogno

Il publisher scrive con un FileShareConfig e il gestore di lettura serve con uno. Se RootPath o UsePerTokenSubfolders differiscono tra loro, l'altro nodo risponde 404. Costruisci la configurazione in un unico posto e registrala una sola volta, così entrambe le metà leggono lo stesso oggetto:

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

Passa asyncPublish: true quando attivi la pubblicazione in background.

FileShareConfig vive in Doconut.Clouds, insieme a AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig e FTPConfig.

ProprietàScopo
LocationCloudLocation.FileShare per una condivisione UNC/local
RootPathLa cartella condivisa a cui ogni nodo può accedere
UsePerTokenSubfoldersMantieni gli artefatti di ogni documento nella propria cartella {token} (predefinita true)
ReadReadyPollMsPer quanto tempo il lato di lettura attende una pagina che una pubblicazione in background sta ancora scrivendo; 0 (il valore predefinito) controlla una volta. Non ha effetto sui documenti pubblicati in modo sincrono

Lato di scrittura — pubblica il documento

Inietta DistributedDocumentPublisher e pubblica invece di aprire una sessione locale. Una chiamata rende e scrive l'intero set di artefatti — pagine, informazioni del documento, indice di ricerca e metadati — e ritorna quando ha terminato:

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 trasporta Token, ArtifactPath, TotalPages e Format. Il token va al browser esattamente come fa un normale token di visualizzatore. In un farm, l'endpoint restituisce anche un ticket di accesso firmato — vedi Sicurezza tra nodi.

Lato di lettura — servire dalla condivisione

Montare il gestore FileShare sul ramo che il client chiama — /doconut, corrispondente a BasePath: 'doconut' — dietro il controllo del ticket:

csharp
var app = builder.Build();

app.UseDoconutResources();
app.Map("/doconut", branch =>
{
    branch.UseDoconutDistributedDocumentSecurity();   // biglietti firmati — vedi sotto
    branch.UseDoconutCloud<FileShareCloudHandler>(options =>
    {
        options.Location          = CloudLocation.FileShare;
        options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
    }, "/");
});

UseDoconutCloud prende il provider come suo argomento di tipo. I gestori sono nominati <Provider>CloudHandler — FileShareCloudHandler, AzureCloudHandler, AmazonS3CloudHandler, GoogleCloudHandler, DropBoxCloudHandler, RedisCloudHandler, FTPCloudHandler, e CDNCloudHandler. Con il prefisso di percorso "/", il gestore risponde a ogni richiesta che raggiunge il suo ramo.

Il gestore CDN è read-only — serve ciò che è già sul CDN; non effettua upload.

Opzionale: pubblicare in background

Per impostazione predefinita PublishAsync rende l'intero documento prima di restituire. Per restituire non appena il token è generato e consentire a un worker ospitato di renderizzare nella stessa cartella, registra la coda opt‑in e costruisci la configurazione condivisa con asyncPublish: true:

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

Senza questa registrazione nulla viene registrato e la pubblicazione rimane sincrona, esattamente come prima.

Quindi chiama EnqueueAsync invece di PublishAsync. (DistributedDocumentPublishOptions.Async è solo un flag che il tuo codice può leggere per scegliere tra i due percorsi; il publisher lo ignora.) La coda è limitata: quando è saturata, EnqueueAsync lancia DistributedPublishQueueFullException. Rispondi con un 503 e un'intestazione Retry-After in modo che i client retrocedano invece di bloccarsi:

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

Pagine non ancora scritte: HTTP 202

Con la pubblicazione in background, una richiesta di pagina può arrivare prima che il worker abbia scritto quella pagina. Il lato di lettura attende fino a ReadReadyPollMs e poi risponde HTTP 202 Accepted invece di bloccare la richiesta.

FirstPagePriority = true abbrevia l'attesa per la prima visualizzazione: la pagina 1 viene scritta nella cartella del documento per prima, così il documento si apre mentre le pagine successive sono ancora in fase di rendering. Si applica solo alla pubblicazione in background nelle cartelle per token (UsePerTokenSubfolders = true); il PublishAsync sincrono lo ignora, perché il suo chiamante attende comunque l'intero documento.

Questo sposta l'attesa sul client, dove è limitata e visibile. Abilita il retry sul widget:

javascript
const objViewer = $('#div_ctlDoc').docViewer({
    BasePath:   'doconut',
    ResPath:    'doconut-res/images',
    retryOn409: true      // tentativi 202 (e legacy 409) risposte di prontezza
});

Un client che non effettua retry mostra tile rotte per le pagine ancora in rendering. Il budget di retry e i suoi valori predefiniti (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs) sono documentati in ConfigurazioneViewer.

Sicurezza tra i nodi

I token legati alla sessione presumono che il nodo di servizio abbia visto la richiesta di apertura. In un farm non lo ha fatto, quindi il controllo per sessione rifiuterebbe richieste legittime; un farm quindi imposta UnsafeMode = true.

UnsafeMode = true non è il modello di sicurezza — è la rimozione di uno che non è più applicabile. Sostituiscilo con ticket di accesso firmati, che ogni nodo può verificare in modo indipendente. Quattro componenti lavorano insieme.

1. Registra la sicurezza dei ticket su ogni nodo. I ticket sono protetti con ASP.NET Core Data Protection, quindi ogni nodo deve usare lo stesso anello di chiavi e il nome dell'applicazione; un nodo con chiavi diverse non può leggere un ticket emesso da un altro nodo.

csharp
using Microsoft.AspNetCore.DataProtection;

builder.Services.AddDataProtection()
    .PersistKeysToFileSystem(new DirectoryInfo(@"\\fileserver\doconut-keys"))   // condiviso da ogni nodo
    .SetApplicationName("doconut-farm");

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

2. Verifica i ticket sul lato lettura. UseDoconutDistributedDocumentSecurity() va sul ramo di lettura prima di UseDoconutCloud, come nel campione lato lettura.

3. Emissione di un ticket quando il documento è aperto. Il ticket indica il token, il browser (tramite un cookie che il lato lettura confronta) e l'utente autenticato, se presente:

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

    // Associa il ticket a questo browser tramite il cookie che controlla il lato di lettura.
    var cookieName = security.Value.BrowserCookieName;   // "doconut-client" per impostazione predefinita
    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. Passa entrambi al widget. Il visualizzatore invia il ticket come access con ogni richiesta:

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

Il lato lettura rifiuta una richiesta il cui ticket è mancante, non valido, emesso per un altro token, scaduto, legato a un altro cookie del browser o emesso per un altro utente autenticato. Risponde 403 — con l'immagine di errore UnauthorizedMessage per le richieste di pagina e miniatura, altrimenti come testo semplice. Prova con un browser reale o un client che conserva i cookie.

Non riportare mai UnsafeMode = true in una distribuzione a nodo singolo, e non trattarlo mai come una scorciatoia per un controllo di sessione fallito su un nodo — lì la correzione corretta è AddSession() / UseSession(). Vedi Sessioni e Sicurezza.

Chiusura di un documento pubblicato

CloseDocument(token) sull'Viewer iniettato elimina una sessione locale. Per rimuovere gli artefatti pubblicati di un documento dalla condivisione, l'editore espone:

text
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)

Passa lo stesso FileShareConfig con cui il documento è stato pubblicato.

Lista di controllo

  1. Costruisci il FileShareConfig in un unico helper, registralo una sola volta e usalo da entrambe le metà.
  2. Imposta RootPath su una cartella raggiungibile da tutti i nodi.
  3. Pubblica con PublishAsync(...), oppure EnqueueAsync(...) con pubblicazione in background.
  4. Servi con UseDoconutCloud<FileShareCloudHandler>(...) sul ramo chiamato dal client.
  5. Con la pubblicazione in background, attiva FirstPagePriority e retryOn409 insieme e assegna al lato di lettura un ReadReadyPollMs diverso da zero.
  6. Sostituisci il controllo per sessione con ticket di accesso firmati — un anello di chiavi Data Protection su ogni nodo, UseDoconutDistributedDocumentSecurity() sul ramo di lettura, un ticket dall'endpoint aperto — e non distribuire UnsafeMode = true da solo.
  7. Verifica aprendo un documento su un nodo e richiedendo una pagina tardiva da un altro.

Questa pagina è stata utile?