LlosLabソフトウェア開発ブログPDF、Delphi、およびドキュメントソフトウェア開発者向けのエンジニアリングノート。

技術記事

FPCでのチャンク化zlib：FlateDecodeに1つのストリームが必要な理由

Delphi PDF Library

Free Pascal上のチャンク化FlateDecodeライターは、1つのzlib状態をすべてのチャンクにわたって生かし続けなければなりません。やりたくなる近道、つまり64 KBのチャンクをそれぞれ独立に圧縮するやり方では、チャンクごとに独自のzlibヘッダーとチェックサムが付くので、1 MiBの添付ファイルが端から端まで継ぎ足された16個のzlibメンバーになります。ISO 32000-1のFlateDecodeが期待しているのはzlibストリームちょうど1つで、標準のデコーダーは最初のend-of-streamマーカーで停止します。つまり最初の65,536バイトより後のデータは、音もなく消えてしまいます。PDF Library for DelphiはDeflateStreamとInflateStreamのどちらでも、1つのzlib状態をすべてのチャンクにわたって生かし続けます

この罠はクロスコンパイラ用ユニットのFPC側にだけ、その中でもチャンク化ストリーミング経路にだけ存在します。だからこそ見逃しやすいのです。Delphi側の分岐も文字列ベースのヘルパーもそれぞれ単一のzlibストリームを生成しますし、小さなテストペイロードはチャンク化コードにそもそも届きません。Delphiが隠しがちな5つのFPC移植の罠で扱った罠たちの近縁ですが、今回はDelphiが何かを覆い隠しているわけではありません。近道の裏には、zlibストリームとは何かという誤ったメンタルモデルがただ横たわっています

チャンク化zlibストリームが他のPDFリーダーで切り詰められるのはなぜか

RFC 1950で定義されるzlibストリームは1つのコンテナであって、その連続ではないからです。仕様に従うinflaterは最初のAdler-32トレーラーをデータの終わりとして扱います。フォーマットは、2バイトのヘッダー、最終ブロックがfinal-blockフラグを運ぶ1本の連続したRFC 1951 deflateビットストリーム、そして展開済み全バイトにわたる4バイトのAdler-32チェックサムです。ISO 32000-1 §7.4.4は/FlateDecodeをまさにその言葉で定義しています。inflateがトレーラーに到達するとZ_STREAM_ENDを返し、残りの入力はavail_inに未読のまま置かれます。inflaterの視点では何も悪くないのでエラーは上げず、トレーラー以降のバイトは単に無視されます。メンバーの連結はgzipでは正当な考え方で（RFC 1952は1つのファイルに複数メンバーを許します）、直感はおそらくそこから来たのでしょうが、zlibにそのような規則はなく、PDFもそれを要求したことはありません

PDFlibPasのFlateDecodeストリームにおけるRFC 1950 zlibメンバーの構造。2バイトのヘッダー、最終ブロックがfinal-blockフラグを運ぶ1本の連続したdeflateビットストリーム、そしてinflateがZ_STREAM_ENDを返す4バイトのAdler-32トレーラー。残りの入力はavail_inに未読のまま、エラーも上げられません
仕様に従うinflaterは最初のAdler-32トレーラーをデータの終わりとして扱うので、メンバー境界は硬い停止点となり、ライターがその後ろに継ぎ足したものは、どのリーダーも復号しない死に重りになります

素朴なFPC版DeflateStreamはソースを一度に64 KBずつ読み込み、各チャンクをZFPCCompressに渡します。このヘルパーは自分のdeflateInit2を実行し、Z_FINISHで圧縮し、deflateEndを呼ぶものです。そのためすべてのチャンクが完全で、有効で、自分で終端を持つzlibストリームとして出てきて、関数はそれらを書き出す前に1つのAnsiStringに連結します。結果はFlateデータに見え、ヘッダーは正しく、エラーなしで復号できます。しかし復号されるのは最初の65,536バイトだけです。読み込み側には鏡写しの罠があります。圧縮入力64 KBごとにZFPCInflateを1回呼ぶやり方では、そのたびに新しいinflateInit2が始まります。2番目のチャンクはzlibヘッダーのないdeflateビットストリームの途中から始まるので、新しいinflaterはそれを拒否します。そして他のプロデューサーが作ったまったく普通の単一メンバーのストリームも、最初の64 KBの圧縮バイトが届く範囲でしか復号されません

FPCでのチャンク化ライターの罠。64 KBのチャンクごとにZFPCCompressを通って完全なzlibメンバーになるため、1 MiBの添付ファイルには継ぎ足された16個のメンバーが入ります。リーダーは65,536バイト後の最初のトレーラーで停止し、それでもGetEmbeddedFileContentToStreamは成功を報告します
被害が見えないのは、どの層も成功しているからです。添付ファイル辞書は完全な/Params /Sizeを掲げ、復号はエラーを上げず、切り詰めに気づくのは添付ファイルを開いた人だけです
// 素朴なチャンク化FPC版DeflateStream（簡略化）：
// ZFPCCompressはdeflateInit2 / deflate(Z_FINISH) / deflateEndを行い、
// 64 KBのチャンクごとに別々のzlibメンバーになってしまう
Repeat
  ReadCount:= Source.Read(Input[1], ChunkSize);
  If (ReadCount> 0) Then
    Compressed:= Compressed+ ZFPCCompress(Copy(Input, 1, ReadCount), 6, False);
Until (ReadCount< ChunkSize);
If (Compressed<> '') Then
  Target.WriteBuffer(PAnsiChar(Compressed)^, Length(Compressed));

PDF Library for Delphiのどの呼び出しがチャンク化経路に届くのか

FPCでは、チャンク化経路は1 MiB以上の埋め込みファイルをすべて書き出し、ストリーミングAPI経由で取り出すFlateストリームは、圧縮サイズが1チャンクを超えた時点からすべて読み込みます。入力データのエンコード方法を決めるのはTPDFStream.ReadFromStreamです。Deflateが真でStream.Size >= 1048576ならDeflateStream経由でストリーミングし、閾値未満ならソース全体をメモリに読んでDeflateStr、つまり全部を1回で圧縮する単発ヘルパーを呼びます。ASCII85＋Flateのフィルターチェーンはサイズ検査を飛ばして常にDeflateStreamを通るので、この経路では64 KBを超えるペイロードは時点で複数チャンクにまたがっています。圧縮を有効にしてReadFromStreamに流れ込む公開エントリーポイントは、埋め込みファイルのライターです：

  • TPDFlib.EmbedFileとTPDFlib.AddEmbeddedFile。ディスク上のファイルを読んで/EmbeddedFileストリームに入れます
  • TPDFlib.AddAssociatedFileFromStreamとTPDFlib.AddAssociatedFileFromFile。電子インボイスXMLなどのソースデータに使うPDF/A-3 associated-fileのライターです
  • 読み込み側ではTPDFlib.GetEmbeddedFileContentToStreamとGetEmbeddedFileContentToFile。TPDFStream.WriteDecodedToStream経由で、そこからさらにInflateStream経由で復号します

ここを間違えると、失敗はあらゆる層で静かに進みます。ライターは元のファイルから計算した/Params /SizeとMD5の/CheckSumを格納するので、ストリームが16個のメンバーを抱えていても、添付ファイル辞書は完全なサイズを掲げ続けます。仕様に従うリーダーなら、同じライブラリのDelphiビルドを含め、最初のZ_STREAM_ENDできれいに停止し、ちょうど65,536バイトを返します。GetEmbeddedFileContentToStreamが1を返すのは、復号がエラーを上げたかどうかを報告するのであって、出力が/Sizeと一致するかどうかを報告するわけではないからです。ギガバイト級PDFのマージと分割で大きな文書の問題を追いかけたことのある人なら、このパターンはお決まりだと知っています。ファイルは開き、ページ数は正しく、被害が見えるのは誰かが添付ファイルを開いたときだけです

すべてのチャンクにわたる1つのdeflate状態

PDFlibZLib.pasのDeflateStreamは、paszlib.TZStreamを1つ初期化し、すべてのチャンクをZ_NO_FLUSH付きでdeflateに供給し、最後にだけZ_FINISHでコンプレッサーを絞り切ってZ_STREAM_ENDが返るまで続けます。こうして出てくるのは、ヘッダーがちょうど1つ、バックリファレンスがチャンク境界をまたげる1本のdeflateビットストリーム、そして入力全体にわたる1つのAdler-32です。FPC側の分岐はDelphi側の分岐と同じ構造をしています。出力も生成されたその場で書き、圧縮結果全体をまずAnsiStringに連結してから書き出す、ということをしないので、ライターがメモリ上に圧縮データの2つ目の完全コピーを作ることはありません

PDFlibPasの単一状態DeflateStream。paszlib.TZStreamを1回だけ初期化し、64 KBのチャンクすべてをZ_NO_FLUSHで供給し、最後にZ_FINISHで絞り切ることで、ヘッダーがちょうど1つ、バックリファレンスがチャンク境界をまたぐ連続したdeflateビットストリームが1本、入力全体のAdler-32が1つだけ出てきます
1つの状態は出力の書き方も変えます。圧縮バイトは2つ目の完全コピーに積まれるのではなく、バッファーが満ちるごとに出て行き、PLDeflateLevelもFPC上の大きな埋め込みファイルに届きます
// 1つのzlib状態を持つFPC版DeflateStream（エラー経路は省略）
If (deflateInit2(strm, Level, Z_DEFLATED, 15, 8, Z_DEFAULT_STRATEGY)<> Z_OK) Then
  Exit;
Try
  Repeat
    ReadCount:= Source.Read(Input[0], ChunkSize);
    If (ReadCount> 0) Then
    Begin
      strm.next_in:= Pointer(Input);
      strm.avail_in:= ReadCount;
      While (strm.avail_in> 0) Do
      Begin
        strm.next_out:= Pointer(Output);
        strm.avail_out:= ChunkSize;
        Status:= deflate(strm, Z_NO_FLUSH);   // 同じ状態、メンバー境界なし
        Produced:= ChunkSize- strm.avail_out;
        If (Produced> 0) Then
          Target.WriteBuffer(Output[0], Produced);
        If (Status<> Z_OK) Then
          Break;
      End;
    End;
  Until (ReadCount< ChunkSize);
  Repeat                                    // 入力全体で1つのトレーラ
    strm.next_out:= Pointer(Output);
    strm.avail_out:= ChunkSize;
    Status:= deflate(strm, Z_FINISH);
    Produced:= ChunkSize- strm.avail_out;
    If (Produced> 0) Then
      Target.WriteBuffer(Output[0], Produced);
  Until (Status= Z_STREAM_END);
Finally
  deflateEnd(strm);
End;

InflateStreamは同じパターンをたどります。1つのinflateInit2、現在のチャンクを使い切り出力バッファーが満杯でなくなるまでinflateを呼び続ける内側のループ、そしてZ_STREAM_ENDでの停止です。知っておく価値のある副作用が1つあります。ライターは固定レベルのヘルパーを経由せず自分でdeflateInit2を呼ぶので、PLDeflateLevelを尊重します。つまりTPDFlib.SetCompressionLevel(1..9)で設定したレベルが、FPC上の大きな埋め込みファイルにも効くのです。DelphiでPDFのファイルサイズを減らすで説明したようにアーカイブ出力向けに圧縮を調整しているなら、これは効いてきます

Flateストリームが単一のzlibメンバーだとどう検証するか

素のzlibデコーダーで展開し、Z_STREAM_ENDが返ってきたときに2つを確認します。復号された長さがソースの長さと等しいこと、そしてavail_inがゼロであることです。終端マーカーの後に入力が残るのが、連結ストリームのシグネチャーです。下のルーチンはこの検査のFPC版で、paszlibの上に直接作られているので、テスト対象のコードを信用しません。続いて、4つの64 KBチャンク、つまり200,000バイトをDeflateStreamに通すプローブが続きます

uses Classes, SysUtils, paszlib, PDFlibZLib;

function IsSingleZlibMember(Packed: TMemoryStream; out Decoded: Int64): Boolean;
var
  strm: TZStream;
  Buf: array[0..65535] of Byte;
  Status: Integer;
begin
  Result:= False;
  Decoded:= 0;
  FillChar(strm, SizeOf(strm), 0);
  if inflateInit2(strm, 15) <> Z_OK then
    Exit;
  try
    strm.next_in:= Packed.Memory;
    strm.avail_in:= Cardinal(Packed.Size);
    repeat
      strm.next_out:= @Buf;
      strm.avail_out:= SizeOf(Buf);
      Status:= inflate(strm, Z_NO_FLUSH);
    until Status <> Z_OK;
    Decoded:= strm.total_out;
    // 1つのメンバーは最後の入力バイトでちょうど終わる
    Result:= (Status = Z_STREAM_END) and (strm.avail_in = 0);
  finally
    inflateEnd(strm);
  end;
end;

// 既定の64 KBチャンクで200,000バイトをDeflateStreamに通し、
// 全長へ復号されるメンバーが1つであることを要求する
Source.Position:= 0;
DeflateStream(Source, Packed);
if not (IsSingleZlibMember(Packed, Decoded) and (Decoded = Source.Size)) then
  raise Exception.Create('DeflateStream produced more than one zlib member');

アプリケーションのレベルで有用なアサーションは、ライブラリが代わりにやってくれないものです。添付ファイルから出てきたものを、入れたときに記録された/Params /Sizeと比較することです。タグ5のGetEmbeddedFileIntPropertyがその記録されたサイズを返し、埋め込みファイルのインデックスは1ベースで、ストリーミング経路を通すにはペイロードが最低1 MiB必要です。出荷するすべてのコンパイラーで同じテストを走らせてください。この種の間違いはDelphiでは通り、FPCでだけ落ちるのですから

procedure CheckLargeAttachmentRoundTrip(const PayloadFile, OutFile: string);
var
  PDF: TPDFlib;
  Extracted: TMemoryStream;
  I, Declared: Integer;
begin
  PDF:= TPDFlib.Create;
  try
    PDF.NewDocument;
    PDF.AddStandardFont(4);
    PDF.DrawText(80, 100, 'Large attachment round trip');
    // 1 MiB以上はReadFromStreamのチャンク化DeflateStream経路へ進む
    if PDF.EmbedFile('Payload', PayloadFile, 'application/octet-stream') <> 1 then
      raise Exception.Create('EmbedFile failed');
    if PDF.SaveToFile(OutFile) <> 1 then
      raise Exception.Create('SaveToFile failed');
  finally
    PDF.Free;
  end;

  PDF:= TPDFlib.Create;
  Extracted:= TMemoryStream.Create;
  try
    if PDF.LoadFromFile(OutFile, '') = 0 then
      raise Exception.Create('LoadFromFile failed');
    for I:= 1 to PDF.EmbeddedFileCount do
    begin
      Extracted.Clear;
      if PDF.GetEmbeddedFileContentToStream(I, Extracted) <> 1 then
        raise Exception.CreateFmt('Attachment %d could not be decoded', [I]);
      Declared:= PDF.GetEmbeddedFileIntProperty(I, 5);   // /Params /Size
      if Extracted.Size <> Declared then
        raise Exception.CreateFmt('Attachment %d truncated: %d of %d bytes',
          [I, Extracted.Size, Declared]);
    end;
  finally
    Extracted.Free;
    PDF.Free;
  end;
end;

FPC側の分岐におけるエッジケース

FPC側の分岐は寛容な復号ルールを使っています。MaxOutputに達すると、FPCのInflateStreamは上限で切り詰めて返りますが、Delphi側の分岐はERangeErrorを上げます。またFPCは、inflateがデータエラーを報告したときにも部分的に復号された出力を受け入れます。切り詰められたストリームやチェックサムの壊れたストリームを出すPDFプロデューサーが実在するからです。何によって書かれたものであれ、連結メンバーを既に含むPDFは、どのリーダーでも最初のZ_STREAM_ENDで停止します。ライブラリ内でストリームを復号して再エンコードすれば直る、などと考えないでください。64 KBの切り詰めを恒久化するだけです。添付ファイルは元のソースから埋め込み直してください。FPCのループは、チャンクに満たない読み込みをデータの終わりとして扱います。これはTFileStreamやTMemoryStreamのようなストリームには成立するので、AddAssociatedFileFromStreamに渡すカスタムTStreamは、まずTMemoryStreamにコピーするのが安全です

単一状態のFPC版DeflateStreamとInflateStreamは、PDF Library for Delphiに同梱されています。1つのソースツリーからDelphi、C++Builder、Free Pascalを対象にしているライブラリで、大きな添付ファイルはDelphiビルドと同じく、FPCビルドからもバイト単位でそのまま返ってきます