Déploiements distribués

Servir un document depuis plusieurs nœuds

Lorsque plusieurs nœuds servent les mêmes documents, le nœud qui rend un document n'est pas forcément celui qui répond aux requêtes de pages du navigateur. Doconut divise cette tâche en deux moitiés explicites — un côté écriture qui publie les artefacts d'un document dans le stockage partagé, et un côté lecture qui les sert depuis n'importe quel nœud.

Un seul nœud n'a pas besoin de tout cela : le chemin normal OpenDocumentAsync conserve le document dans la mémoire de ce nœud et le lie à la session du navigateur (voir Sessions et Sécurité). Utilisez cette page lorsque les requêtes de pages peuvent arriver sur un nœud qui n'a jamais vu l'ouverture.

Comment les deux moitiés s'emboîtent

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 configuration partagée dont les deux moitiés ont besoin

Le côté écriture écrit avec un FileShareConfig et le côté lecture sert avec un. Si RootPath ou UsePerTokenSubfolders diffèrent entre eux, l'autre nœud renvoie 404. Construisez la configuration à un seul endroit et enregistrez‑la une fois, afin que les deux moitiés lisent le même objet :

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

Passez asyncPublish: true lorsque vous activez la publication en arrière‑plan.

FileShareConfig se trouve dans Doconut.Clouds, avec AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig et FTPConfig.

PropriétéObjectif
LocationCloudLocation.FileShare pour un partage UNC/local
RootPathLe dossier partagé accessible par chaque nœud
UsePerTokenSubfoldersConservez les artefacts de chaque document dans son propre dossier {token} (par défaut true)
ReadReadyPollMsDurée d'attente du côté lecture pour une page qu'une publication en arrière‑plan est encore en train d'écrire ; 0 (la valeur par défaut) vérifie une fois. Cela n'affecte pas les documents publiés de façon synchrone

Côté écriture — publier le document

Injectez DistributedDocumentPublisher et publiez au lieu d'ouvrir une session locale. Un appel rend et écrit l'ensemble complet des artefacts — pages, informations du document, index de recherche et métadonnées — et renvoie lorsque c'est terminé :

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 transporte Token, ArtifactPath, TotalPages et Format. Le token est envoyé au navigateur exactement comme le fait un token de visionneur normal. Dans un farm, le point de terminaison renvoie également un ticket d'accès signé — voir Sécurité entre les nœuds.

Côté lecture — servir depuis le partage

Montez le gestionnaire FileShare sur la branche appelée par le client — /doconut, correspondant à BasePath: 'doconut' — derrière la vérification du ticket :

csharp
var app = builder.Build();

app.UseDoconutResources();
app.Map("/doconut", branch =>
{
    branch.UseDoconutDistributedDocumentSecurity();   // tickets signés — voir ci-dessous
    branch.UseDoconutCloud<FileShareCloudHandler>(options =>
    {
        options.Location          = CloudLocation.FileShare;
        options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
    }, "/");
});

UseDoconutCloud prend le fournisseur comme argument de type. Les gestionnaires sont nommés <Provider>CloudHandler — FileShareCloudHandler, AzureCloudHandler, AmazonS3CloudHandler, GoogleCloudHandler, DropBoxCloudHandler, RedisCloudHandler, FTPCloudHandler et CDNCloudHandler. Avec le préfixe de chemin "/", le gestionnaire répond à chaque requête qui atteint sa branche.

Le gestionnaire CDN est read-only — il sert ce qui est déjà sur le CDN ; il ne téléverse rien.

Optionnel : publier en arrière‑plan

Par défaut, PublishAsync rend le document complet avant de retourner. Pour retourner dès que le jeton est créé et laisser un worker hébergé rendre dans le même dossier, enregistrez la file d’attente d’opt‑in, et construisez la configuration partagée avec asyncPublish: true :

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

Sans cet enregistrement, rien n’est enregistré et la publication reste synchrone, exactement comme avant.

Appelez alors EnqueueAsync au lieu de PublishAsync. (DistributedDocumentPublishOptions.Async n’est qu’un drapeau que votre propre code peut lire pour choisir entre les deux chemins ; l’éditeur l’ignore.) La file d’attente est bornée : lorsqu’elle est saturée, EnqueueAsync lève DistributedPublishQueueFullException. Répondez avec un 503 et un en‑tête Retry-After afin que les clients se désengagent plutôt que de rester bloqués :

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

Pages non encore écrites : HTTP 202

Avec la publication en arrière‑plan, une requête de page peut arriver avant que le worker n’ait écrit cette page. Le côté lecture attend jusqu’à ReadReadyPollMs puis répond HTTP 202 Accepted au lieu de bloquer la requête.

FirstPagePriority = true raccourcit l’attente pour la première vue : la page 1 est écrite d’abord dans le dossier du document, de sorte que le document s’ouvre pendant que les pages suivantes sont encore en cours de rendu. Cela ne s’applique qu’à la publication en arrière‑plan dans des dossiers par jeton (UsePerTokenSubfolders = true) ; le PublishAsync synchrone l’ignore, car son appelant attend tout de même le document complet.

Cela déplace l’attente vers le client, où elle est bornée et visible. Activez la nouvelle tentative sur le widget :

javascript
const objViewer = $('#div_ctlDoc').docViewer({
    BasePath:   'doconut',
    ResPath:    'doconut-res/images',
    retryOn409: true      // tentatives 202 (et legacy 409) réponses de disponibilité
});

Un client qui ne réessaie pas affiche des tuiles cassées pour les pages qui sont encore en cours de rendu. Le budget de nouvelles tentatives et ses valeurs par défaut (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs) sont documentés dans ViewerConfig.

Sécurité entre nœuds

Les jetons liés à la session supposent que le nœud serveur a vu la requête d'ouverture. Dans un farm, ce n'est pas le cas, de sorte que la vérification par session rejetterait les requêtes légitimes ; un farm définit donc UnsafeMode = true.

UnsafeMode = true n'est pas le modèle de sécurité — c'est la suppression d'un modèle qui n'est plus applicable. Remplacez-le par des tickets d'accès signés, que chaque nœud peut vérifier de façon indépendante. Quatre éléments fonctionnent ensemble.

1. Enregistrer la sécurité des tickets sur chaque nœud. Les tickets sont protégés avec ASP.NET Core Data Protection, ainsi chaque nœud doit utiliser le même trousseau de clés et le même nom d'application ; un nœud avec des clés différentes ne peut pas lire un ticket émis par un autre nœud.

csharp
using Microsoft.AspNetCore.DataProtection;

builder.Services.AddDataProtection()
    .PersistKeysToFileSystem(new DirectoryInfo(@"\\fileserver\doconut-keys"))   // partagé par chaque nœud
    .SetApplicationName("doconut-farm");

builder.Services.AddDoconut(options => options.UnsafeMode = true);
builder.Services.AddDoconutDistributedDocumentSecurity(options =>
{
    options.TicketLifetimeMinutes = 60;   // la valeur par défaut
});

2. Vérifier les tickets côté lecture. UseDoconutDistributedDocumentSecurity() se place sur la branche de lecture avant UseDoconutCloud, comme dans l'exemple côté lecture.

3. Émettre un ticket lorsque le document est ouvert. Le ticket indique le jeton, le navigateur (via un cookie que le côté lecture compare), et l'utilisateur connecté, le cas échéant :

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

    // Liez le ticket à ce navigateur via le cookie que le côté lecture vérifie.
    var cookieName = security.Value.BrowserCookieName;   // "doconut-client" par défaut
    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. Transmettre les deux au widget. Le visualiseur envoie le ticket comme access avec chaque requête :

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

Le côté lecture refuse une requête dont le ticket est manquant, invalide, émis pour un autre jeton, expiré, lié à un autre cookie de navigateur, ou émis pour un autre utilisateur connecté. Il répond 403 — avec l'image d'erreur UnauthorizedMessage pour les requêtes de page et de vignette, sinon en texte brut. Testez avec un vrai navigateur ou un client qui conserve les cookies.

Ne ramenez jamais UnsafeMode = true dans un déploiement à nœud unique, et ne le considérez jamais comme un raccourci pour une vérification de session échouée sur un nœud — la solution correcte est alors AddSession() / UseSession(). Voir Sessions & Security.

Fermeture d'un document publié

CloseDocument(token) sur le Viewer injecté libère une session locale. Pour supprimer les artefacts publiés d'un document du partage, l'éditeur expose :

text
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)

Passez le même FileShareConfig avec lequel le document a été publié.

Checklist

  1. Construisez le FileShareConfig dans un seul helper, enregistrez‑le une fois, et utilisez‑le depuis les deux moitiés.
  2. Pointez RootPath vers un dossier accessible par chaque nœud.
  3. Publiez avec PublishAsync(...), ou EnqueueAsync(...) avec la publication en arrière‑plan.
  4. Servez avec UseDoconutCloud<FileShareCloudHandler>(...) sur la branche appelée par le client.
  5. Avec la publication en arrière‑plan, activez FirstPagePriority et retryOn409 simultanément, et attribuez à la partie lecture un ReadReadyPollMs non nul.
  6. Remplacez la vérification par session par des tickets d’accès signés — un anneau de clés Data Protection sur chaque nœud, UseDoconutDistributedDocumentSecurity() sur la branche de lecture, un ticket provenant du point d’accès ouvert — et n’expédiez pas UnsafeMode = true seul.
  7. Vérifiez en ouvrant un document sur un nœud et en demandant une page tardive depuis un autre.

Cette page était-elle utile ?