Distribuzioni Distribuite

Fornisce un documento da più nodi

Quando più nodi servono 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 write side che pubblica gli artefatti di un documento nello storage condiviso, e un read side che li serve da qualsiasi nodo.

Un singolo nodo non ha bisogno di nulla di tutto ciò: il normale percorso 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

L'editore scrive con un FileShareConfig e il gestore di lettura serve con uno. Se RootPath o UsePerTokenSubfolders differiscono, l'altro nodo restituisce 404. Crea la configurazione in un unico luogo e registrala una sola volta, così entrambe le metà leggono lo stesso oggetto:

csharp
var rootPath = builder.Configuration["Doconut:SharedRoot"]!;   // ad 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 si trova 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 sua propria cartella {token} (predefinita true)
ReadReadyPollMsQuanto tempo il read side 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

Inject 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 viene inviato 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 i nodi.

Lato di lettura — servire dalla condivisione

Monta 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 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 è sola lettura — serve ciò che è già sul CDN; non effettua upload.

Facoltativo: 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.

Chiama quindi EnqueueAsync invece di PublishAsync. (DistributedDocumentPublishOptions.Async è solo un flag che il tuo codice può leggere per scegliere tra i due percorsi; il pubblicatore lo ignora.) La coda è limitata: quando è saturata, EnqueueAsync lancia DistributedPublishQueueFullException. Rispondi con un 503 e un'intestazione Retry-After in modo che i client si ritirino anziché 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 readiness
});

Un client che non effettua retry mostra tasselli rotti 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 iniziale. 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. Sostituirlo con ticket di accesso firmati, che ogni nodo può verificare in modo indipendente. Quattro componenti lavorano insieme.

1. Registrare la sicurezza dei ticket su ogni nodo. I ticket sono protetti con ASP.NET Core Data Protection, quindi ogni nodo deve utilizzare lo stesso anello di chiavi e 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. Verificare 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 il lato di lettura verifica.
    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. Passare 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. Testare con un browser reale o un client che conserva i cookie.

Non riportare mai UnsafeMode = true in un'implementazione a nodo singolo, e non considerarlo mai 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)

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

Lista di controllo

  1. Costruisci il FileShareConfig in un unico helper, registralo una sola volta e usalo da entrambe le metà.
  2. Punta 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?