Artigo Técnico

HotPDF: streaming de PDFs remotos com Range Coalescing

Um PDF que abre instantaneamente de um disco local pode levar vários segundos para mostrar a primeira página quando os mesmos bytes vêm de um servidor HTTP que responde range requests, mesmo sendo o arquivo de poucos megabytes e o link rápido. A largura de banda não é o problema. A contagem de pedidos é, e a cura é transformar centenas de leituras mínimas espalhadas em algumas dúzias de blocos em cache, para então ler adiante só enquanto o padrão de acesso continua sequencial

Por que o mesmo PDF carrega instantâneo do disco e rasteja por HTTP?

Um parser de PDF não lê um arquivo de frente para trás. Ele navega por um. A estrutura na ISO 32000-1 §7.5 põe o ponto de entrada no fim: o parser busca o último kilobyte pelo startxref, salta para a tabela de referências cruzadas, resolve o dicionário trailer, segue uma referência ao Catalog, depois à raiz da árvore de páginas, depois a um nó de página, depois ao dicionário de recursos dessa página. Cada salto lê dezenas de bytes de um offset diferente, e um arquivo com atualizações incrementais repete a caminhada uma vez por revisão pela cadeia de /Prev

Num arquivo local esse padrão é quase gratuito, porque o sistema operacional já segura a página de 4 KiB vizinha no cache de arquivos dele e a segunda leitura custa uma cópia de memória. Um transporte de rede não tem localidade nenhuma assim. Toda leitura vira um pedido com latência própria, e a aritmética é brutal: a 40 ms por round trip, 300 leituras pequenas somam doze segundos de espera enquanto o fio fica majoritariamente ocioso. Ler menos não é opção, já que o parser precisa exatamente dos bytes que pede. O que pode mudar é quanto cada pedido físico traz de volta

Envolvendo o seu transporte num THPDFCoalescingRandomAccessSource

O HotPDF carrega documentos de qualquer classe que desça de THPDFRandomAccessSource, e o THPDFCoalescingRandomAccessSource senta entre essa classe e o parser. Toda leitura é arredondada para um bloco alinhado e o bloco fica em memória. O BlockSize tem 262.144 bytes como padrão e o MaxCacheBytes 2.097.152, então oito blocos ficam residentes e o menos recentemente usado sai quando o orçamento enche. A busca de 40 bytes por uma chave de trailer do parser puxa os 256 KiB em volta, e a próxima dúzia de leituras naquela vizinhança (entradas de referências cruzadas, o Catalog, chaves da árvore de páginas) sai da memória

A sua própria classe continua enxuta. Dois métodos são obrigatórios: GetSize e ReadAt. Sobrescreva o ReadAtCancellable quando o seu cliente HTTP puder abortar um pedido em voo, e sobrescreva o IsRangeAvailable quando a fonte é um download ainda em andamento. O wrapper faz essa pergunta antes de cada busca: se um bloco inteiro ainda não está lá, ele tenta de novo com só os bytes pedidos, e se esses também estiverem ausentes a leitura volta curta em vez de bloquear

Diagrama de coalescência de blocos do HotPDF: buscas espalhadas do parser são arredondadas para cima em blocos de 256 KiB em cache, então leituras posteriores na mesma vizinhança são servidas da memória
leituras são arredondadas para cima para blocos de 256 KiB em cache por padrão, então a dispersão do parser custa uma transferência de rede por vizinhança
type
  // TMyHttpClient representa a sua própria classe de cliente HTTP
  THttpRangeSource = class(THPDFRandomAccessSource)
  private
    FClient: TMyHttpClient;
    FUrl: string;
    FSize: Int64;
  public
    constructor Create(const AUrl: string);
    function GetSize: Int64; override;
    function ReadAt(Offset: Int64; var Buffer; Count: Longint): Longint; override;
    function ReadAtCancellable(Offset: Int64; var Buffer; Count: Longint;
      CancellationToken: THPDFCancellationToken): Longint; override;
  end;

var
  Raw: THttpRangeSource;
  Cached: THPDFCoalescingRandomAccessSource;
  Pdf: THotPDF;
begin
  Raw := THttpRangeSource.Create('https://files.example.com/contract.pdf');
  // OwnsSource=True: o wrapper libera o Raw; blocos de 256 KiB, orçamento de 8 MiB
  Cached := THPDFCoalescingRandomAccessSource.Create(Raw, True, 262144, 8388608);
  Cached.MaxReadAheadBlocks := 8;   // faixa válida 1..32
  Pdf := THotPDF.Create(nil);
  try
    // OwnsSource=True de novo: o Pdf libera o Cached, que libera o Raw
    if Pdf.LoadFromRandomAccessSource(Cached, True) > 0 then
      RenderFirstPage(Pdf);   // código seu
  finally
    Pdf.Free;
  end;
end;

Prefetch assíncrono e read-ahead adaptativo estão ambos ligados assim que o wrapper é construído, então o exemplo só toca no teto da janela. O construtor valida os argumentos dele de cara: o BlockSize precisa estar entre 4.096 e 16.777.216 bytes e o MaxCacheBytes precisa segurar pelo menos um bloco, senão você leva um ERangeError antes de um único byte se mover

Você não precisa estritamente do wrapper explícito. Entregue ao LoadFromRandomAccessSource uma fonte simples e o HotPDF a embrulha para você, usando a política de cache bruto que você pode ler e mudar via GetCacheAdmissionPolicy e SetCacheAdmissionPolicy com a camada clkRawCompressed: oito entradas, 2 MiB no total, 256 KiB por entrada. Passe o seu próprio THPDFCoalescingRandomAccessSource e ele é usado exatamente como configurado. Para qualquer coisa que cruze uma rede, monte o wrapper você mesmo; você ganha os controles de read-ahead e o record completo de estatísticas, enquanto o caminho automático reporta só contagens de hit, miss, admissão e eviction via GetCacheAdmissionStatistics

Até onde ele deve ler?

O read-ahead adaptativo decide documento a documento. Com o AdaptiveReadAheadEnabled definido, toda leitura que o parser faz pelo documento carregado é classificada como sequencial ou aleatória, e a janela de prefetch segue um escore. Duas leituras para frente consecutivas abrem a janela para dois blocos, quatro abrem para quatro, seis abrem para oito. A janela nunca excede o MaxReadAheadBlocks, e nunca excede o número de blocos que cabem no MaxCacheBytes, então um cache pequeno não pode ser inundado pelo próprio prefetch dele

Uma leitura que salta para trás, ou aterrissa longe demais do fim da leitura anterior, derruba o escore abaixo de zero. A janela fecha, qualquer prefetch indo para outro lugar é cancelado, e o SuppressedPrefetchCount sobe. Duas leituras para frente depois a janela reabre com um único bloco. Esse atraso é o objetivo: uma leitura contígua sortuda no meio de uma caçada de referências cruzadas não reinicia a especulação

O SequentialReadToleranceBytes, 4.096 por padrão, define "longe demais". Um parser caminhando por um fluxo de conteúdo não produz offsets perfeitamente contíguos; ele pula um campo de comprimento aqui, um dicionário de imagem inline ali. Leituras que aterrissam dentro da tolerância do fim anterior ainda contam como para frente. Defina baixo demais e uma varredura normal para frente é classificada como aleatória, então o read-ahead nunca engata. Defina alto demais e acesso aleatório genuíno parece sequencial, e você busca megabytes que ninguém lê. O setter aceita qualquer valor de zero até BlockSize e reinicia o escore quando muda

Crescimento é gradual, colapso é imediato, e essa assimetria é deliberada. Buscar demais numa carga aleatória queima largura de banda real, e num transporte medido dinheiro real; buscar de menos numa sequencial custa alguns round trips extras. Deixe o AdaptiveReadAheadEnabled ligado. Desligado, o wrapper prefetcha um bloco depois de toda leitura sem olhar o padrão, que é exatamente o comportamento errado enquanto o parser salta entre seções de referências cruzadas

Diagrama em escada do read-ahead adaptativo no HotPDF crescendo um, dois, quatro e oito blocos em leituras para frente sustentadas com colapso imediato em acesso fora de ordem
o crescimento sobe um degrau da escada por vez enquanto o colapso é imediato — o erro barato é o preferido em transportes medidos

A classificação é guiada pelo stream de que o HotPDF lê durante um load. Se o seu próprio código também puxa bytes pelo wrapper, por exemplo para hashear um arquivo ou extrair um anexo, chame o ObserveReadPattern com o offset e o comprimento depois de cada leitura para que a janela reaja a esse tráfego também. Quando você já sabe quais bytes serão queridos em seguida, o PrefetchRange inicia uma busca em segundo plano direto; o IsPrefetchActive reporta se uma ainda está rodando

Mantendo blocos quentes quando o cache enche

A remoção least-recently-used simples tem uma fraqueza conhecida. Uma longa passada para frente, digamos por uma imagem embutida grande, empurra para fora todo bloco a que o parser volta sempre, incluindo os blocos de referências cruzadas e de Catalog de que ele vai precisar de novo na próxima página. O THPDFCoalescingRandomAccessSource conta quantas vezes cada bloco foi pedido, e uma vez que o orçamento enche um bloco novo só entra no cache se foi pedido pelo menos tantas vezes quanto o bloco que substituiria. Caso contrário a leitura vai direto à sua fonte por exatamente os bytes pedidos, e o RejectionCount e o FrequencyRejectionCount registram

Essa regra vem ligada por padrão (o argumento de construtor AdaptiveAdmission). O ConfigureCacheAdmission muda o orçamento de bytes, o teto por entrada, um limite opcional de contagem de entradas e a regra de admissão num wrapper vivo; ele cancela qualquer prefetch rodando e apara o cache para os novos limites na hora

Cancelamento que realmente para a transferência

O prefetch roda numa única thread de segundo plano, e o wrapper o cancela assim que deixa de valer a pena terminar. Uma leitura em primeiro plano por bytes fora do range sendo prefetchado o cancela, então a página que o usuário pediu nunca espera atrás de tráfego especulativo. Uma leitura aleatória o cancela. Destruir o wrapper, ou chamar CancelPrefetch ou ClearCache, o cancela e espera a thread sair. Cada um desses define o THPDFCancellationToken que a thread de prefetch passa ao seu ReadAtCancellable

Se os bytes de fato param de fluir depende da sua sobrecarga. O ReadAtCancellable padrão no THPDFRandomAccessSource checa o token antes e depois de um ReadAt simples, o que basta para um compartilhamento de arquivos mas deixa uma resposta HTTP de 256 KiB pela metade correr até o fim. Um cliente que lê o corpo da resposta em chunks pode checar o token entre chunks e abortar:

function THttpRangeSource.ReadAt(Offset: Int64; var Buffer;
  Count: Longint): Longint;
begin
  Result := ReadAtCancellable(Offset, Buffer, Count, nil);
end;

function THttpRangeSource.ReadAtCancellable(Offset: Int64; var Buffer;
  Count: Longint; CancellationToken: THPDFCancellationToken): Longint;
var
  Status: Integer;
begin
  if CancellationToken <> nil then
    CancellationToken.ThrowIfCancellationRequested('http range read');
  // GetRange e o callback dele são a API do seu cliente: ele envia
  // "Range: bytes=Offset-(Offset+Count-1)" e chama o callback entre chunks do corpo
  Result := FClient.GetRange(FUrl, Offset, Count, Buffer, Status,
    function: Boolean
    begin
      Result := (CancellationToken <> nil) and
        CancellationToken.IsCancellationRequested;
    end);
  // 200 em vez de 206 significa que o servidor ignorou o Range e enviou o arquivo inteiro
  if Status <> 206 then
    raise EStreamError.CreateFmt('Range request not honored (HTTP %d)', [Status]);
  if CancellationToken <> nil then
    CancellationToken.ThrowIfCancellationRequested('http range read');
end;

A checagem de status cobre a armadilha que a maioria das fontes HTTP encontra primeiro. O RFC 9110 §14 deixa um servidor ignorar um header Range e responder 200 com a representação completa, e algumas configurações de CDN e proxy fazem exatamente isso para certos arquivos. Uma fonte que copia os primeiros Count bytes de uma resposta 200 entrega ao parser bytes do offset zero não importa qual offset foi pedido. Valores de retorno também importam: o wrapper levanta EStreamError se o ReadAt reportar contagem negativa ou mais bytes que os pedidos, e trata zero como fim de dados

O único token não nulo que a sua fonte recebe pertence à thread de prefetch. Leituras do parser durante um load chegam ao seu ReadAtCancellable com token nulo, então parar o load em si é um interruptor separado: atribua um token ao THotPDF.OperationCancellationToken, e o carregamento do documento o checa no caminho. O mesmo modelo de token comanda a fila descrita em renderização em segundo plano com uma fila de requisições, então um visualizador pode cancelar um load, os renders dele e o tráfego de rede especulativo dele a partir de um único handler de fechamento

Lendo as estatísticas do cache de ranges

O GetStatistics preenche um record THPDFRangeCacheStatistics que separa o que o seu transporte fez do que o cache fez. SourceReadCount e SourceBytesRead são tráfego físico. CacheHitCount e CacheMissCount são tráfego lógico. SequentialReadCount e RandomReadCount mostram como o padrão de acesso foi classificado, CurrentReadAheadBlocks e PeakReadAheadBlocks mostram até onde a janela abriu, e os quatro contadores de prefetch mostram se a especulação valeu. CachedRangeCount, CachedBytes, EvictionCount e RejectionCount descrevem o cache em si

var
  S: THPDFRangeCacheStatistics;
begin
  Cached.GetStatistics(S);
  Log(Format('physical %d reads / %d bytes, hits %d, misses %d',
    [S.SourceReadCount, S.SourceBytesRead, S.CacheHitCount, S.CacheMissCount]));
  Log(Format('pattern: %d sequential, %d random, peak window %d blocks',
    [S.SequentialReadCount, S.RandomReadCount, S.PeakReadAheadBlocks]));
  Log(Format('prefetch: %d issued, %d completed, %d canceled, %d suppressed',
    [S.PrefetchRequestCount, S.PrefetchCompletedCount,
     S.PrefetchCancelledCount, S.SuppressedPrefetchCount]));
  Log(Format('cache: %d blocks / %d bytes, %d evicted, %d rejected',
    [S.CachedRangeCount, S.CachedBytes, S.EvictionCount, S.RejectionCount]));

  // Rejeições se acumulando num documento majoritariamente sequencial: dê mais espaço a ele
  if S.RejectionCount > S.CacheHitCount then
    Cached.ConfigureCacheAdmission(16 * 1024 * 1024, Cached.BlockSize, 0);
end;

Três leituras dizem o que mudar. Muitos prefetches cancelados ao lado de uma contagem alta de leituras aleatórias significam que o documento está sendo caminhado fora de ordem, então abaixe o MaxReadAheadBlocks e pare de pagar por largura de banda que você joga fora. Muitos misses com a janela de pico presa em 1 significam que a tolerância está rejeitando um padrão que na prática é sequencial, então suba o SequentialReadToleranceBytes. SourceBytesRead muito acima do tamanho do arquivo significa que blocos são removidos antes de serem usados de novo; suba o MaxCacheBytes antes de tocar em qualquer outra coisa. O limiar de rejeição no exemplo é a nossa própria heurística de partida, então ajuste contra o seu tráfego

Painel do HotPDF mapeando as três leituras de THPDFRangeCacheStatistics para os ajustes de MaxReadAheadBlocks, SequentialReadToleranceBytes e MaxCacheBytes
cada leitura de sintoma nomeia o conserto dela, de abaixar a janela em caminhadas aleatórias a alargar o cache quando blocos ficam trocando

Arquivos linearizados mudam a aritmética

Se você controla o produtor, linearizar o documento muda o problema em vez de afiná-lo. O Anexo F da ISO 32000-1 põe os objetos da primeira página e uma hint table na frente do arquivo, então um visualizador pode renderizar a página um a partir dos bytes de abertura sem tocar no resto. O HotPDF expõe esse caminho por GetProgressiveLinearizedLoadInfo e ReadProgressiveLinearizedFirstPageSection, ambos recebendo o mesmo THPDFRandomAccessSource que você embrularia para coalescência; o lado da escrita é coberto em gerar PDFs linearizados com hint tables

As duas técnicas se compõem. A coalescência torna qualquer documento tolerável num link lento, incluindo arquivos de terceiros que você não pode ressalvar; a linearização faz a primeira página chegar rápido em documentos que você mesmo produz. Arquivos num disco local grandes demais para a memória são um problema diferente, sem latência de round trip para amortizar, e os caminhos de arquivo mapeado e lazy stream em o fluxo de trabalho da API de arquivo direto servem melhor a eles

As classes de fonte de acesso aleatório, o wrapper de coalescência, as políticas de admissão de cache e as chamadas de carregamento linearizado progressivo vêm todas com o HotPDF, um componente de PDF nativo para Delphi e C++Builder com código-fonte completo. Licenciamento e a referência completa da API estão na página do componente HotPDF Delphi PDF