Rust と unoserver による文書変換の自動化
Rust から unoserver の unoconvert クライアントを呼び出し、単一の文書やフォルダー内の文書を PDF に変換します。以下の CLI は入力ファイル名を省略せずに保持し、既存の出力ディレクトリを拒否し、選択したファイルのいずれかが失敗すると非ゼロの終了コードを返します。Rust がファイルを順番に処理する間、LibreOffice はループバック上のワーカーで実行し続けます。
unoserver と Rust の依存関係のインストール
LibreOffice の Writer、Calc、Impress コンポーネントと、対応する Python UNO ブリッジ、Python の venv サポートをインストールした Linux を使用します。Debian/Ubuntu では、libreoffice、python3-uno、python3-venv パッケージで提供されます。Rust のインストール手順に従い、メンテナンスされている Rust ツールチェーンと Cargo をインストールします。検証したバージョンは Rust/Cargo 1.98.1、Python 3.14.7、LibreOffice 26.8.0.3、unoserver 3.7 です。コンパイラーのバージョンは検証時の記録であり、この例で厳密に固定する必要はありません。
Cargo の依存関係を持たない新しいプロジェクトを作成します。空の [workspace] テーブルにより、プロジェクト自体がワークスペースルートになるため、セットアップ時に親プロジェクトのマニフェストへメンバーが追加されることはありません。サブシェルを使うため、ターミナルの作業ディレクトリは変わりません。また、mkdir は既存のプロジェクトを拒否します。
(
command -v cargo >/dev/null &&
command -v rustc >/dev/null &&
mkdir doc_converter_rust &&
cd doc_converter_rust &&
mkdir src &&
cat > Cargo.toml <<'TOML'
[package]
name = "doc_converter_rust"
version = "0.1.0"
edition = "2021"
[workspace]
TOML
)
プロジェクトを作成したディレクトリから、各ターミナルで cd doc_converter_rust を実行します。以降のコマンドは、そのプロジェクトディレクトリで実行します。バージョンを固定したクライアントとサーバーを、このプロジェクトの venv にインストールします。
python3 -m venv --system-site-packages .venv &&
.venv/bin/python -c 'import uno' &&
.venv/bin/python -m pip install unoserver==3.7 &&
.venv/bin/unoconvert --version
インストールを続行するには、UNO のインポートが成功する必要があります。失敗した場合は、その Python インタープリターに正確に対応するブリッジをインストールし、このブロックを再実行します。作成途中の venv を再利用するため、プロジェクトファイルは置き換えません。デフォルトの隔離された pipx 環境からは、ブリッジが見えない場合があります。unoserver のインストールガイドでは、この Python と LibreOffice の組み合わせについて説明しており、macOS と Windows はサポート対象外としています。この手順では Linux を扱います。
一方のターミナルで、両インターフェースをループバックにバインドし、別々のポートでワーカーを実行します。
.venv/bin/python - <<'PY' &&
import socket
for port in (2003, 2002):
with socket.socket() as listener:
listener.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
try:
listener.bind(('127.0.0.1', port))
except OSError as error:
raise SystemExit(f'Loopback port {port} is unavailable: {error}')
PY
.venv/bin/unoserver --interface 127.0.0.1 --port 2003 \
--uno-interface 127.0.0.1 --uno-port 2002 --conversion-timeout 120
そのターミナルは開いたままにします。起動後、もう一方のターミナルからワーカーを確認します。
.venv/bin/unoping --host 127.0.0.1 --port 2003
unoserver 3.7 と LibreOffice を含むバージョン情報が表示されることを確認します。ポートチェックは、LibreOffice の起動前に既存のリスナーを検出すると処理を拒否します。失敗した場合は空いているポートの組を選び、プローブ、サーバーフラグ、以下の Rust クライアントのポートを一致するように更新します。正体が不明な既存のリスナーには接続しないでください。チェックは起動前にソケットを解放します。その隙間にリスナーが現れて起動が失敗した場合は、再試行する前に、このワーカーの残存する LibreOffice 子プロセスを停止します。両インターフェースには認証がありません。また、変換がハングした場合、変換タイムアウトにより LibreOffice が終了し、サーバーも終了します。詳細はクライアント/サーバーのドキュメントを参照してください。両ポートを非公開に保ってください。作業が終わったら、ワーカーのターミナルで Ctrl+C を押して停止します。
Rust と unoserver の連携
この完全な CLI を src/main.rs として保存します。単一のファイルまたはディレクトリを受け取り、新しい出力ディレクトリを必要とします。各 PDF の名前には入力ファイル名全体に .pdf を追加するため、report.doc と report.docx が衝突することはありません。プロセス引数に渡すファイルシステムパスは、情報が失われる文字列に変換せず、ネイティブのパスとして保持します。
use std::error::Error;
use std::ffi::OsStr;
use std::fs::{self, DirBuilder, File};
use std::io::{self, Read};
use std::os::unix::fs::DirBuilderExt;
use std::path::{Path, PathBuf};
use std::process::{Command, ExitCode};
type Result<T> = std::result::Result<T, Box<dyn Error>>;
fn supported(path: &Path) -> bool {
let extension = path.extension().and_then(OsStr::to_str).unwrap_or("").to_ascii_lowercase();
matches!(extension.as_str(), "doc" | "docx" | "odt" | "rtf" | "txt" |
"ppt" | "pptx" | "odp" | "xls" | "xlsx" | "ods" | "csv")
}
fn convert_one(input: &Path, output: &Path) -> Result<()> {
let candidate = output.join(".conversion.pdf");
let conversion = (|| -> Result<()> {
let status = Command::new("unoconvert")
.args(["--host", "127.0.0.1", "--port", "2003", "--host-location", "local"])
.arg(input).arg(&candidate).status()?;
if !status.success() {
return Err(io::Error::other("unoconvert failed").into());
}
let mut header = [0; 5];
File::open(&candidate)?.read_exact(&mut header)?;
if &header != b"%PDF-" {
return Err(io::Error::other("conversion did not produce a PDF").into());
}
let mut filename = input.file_name().ok_or_else(|| io::Error::other("missing filename"))?.to_os_string();
filename.push(".pdf");
// Same-filesystem publication must fail rather than overwrite a destination.
fs::hard_link(&candidate, output.join(filename))?;
Ok(())
})();
if candidate.exists() {
fs::remove_file(&candidate)?;
}
conversion
}
fn run() -> Result<()> {
let args: Vec<_> = std::env::args_os().skip(1).collect();
if args.len() != 2 {
return Err(io::Error::other("Usage: doc_converter_rust <input-file-or-directory> <new-output-directory>").into());
}
let source = PathBuf::from(&args[0]);
let metadata = fs::symlink_metadata(&source)?;
let mut inputs = Vec::new();
if metadata.is_file() && supported(&source) {
inputs.push(source.canonicalize()?);
} else if metadata.is_dir() {
for entry in fs::read_dir(&source)? {
let entry = entry?;
if entry.file_type()?.is_file() && supported(&entry.path()) {
inputs.push(entry.path().canonicalize()?);
}
}
} else {
return Err(io::Error::other("use a supported regular file or directory, not a symlink").into());
}
inputs.sort();
if inputs.is_empty() {
return Err(io::Error::other("no supported documents found").into());
}
let output = PathBuf::from(&args[1]);
DirBuilder::new().mode(0o700).create(&output)?;
let output = output.canonicalize()?;
let mut failures = 0;
for input in inputs {
match convert_one(&input, &output) {
Ok(()) => println!("Converted {}", input.display()),
Err(_) => {
failures += 1;
eprintln!("Conversion failed for {}", input.display());
}
}
}
if failures > 0 {
return Err(io::Error::other(format!("{failures} conversion(s) failed")).into());
}
Ok(())
}
fn main() -> ExitCode {
match run() {
Ok(()) => ExitCode::SUCCESS,
Err(error) => {
eprintln!("Document conversion failed: {error}");
ExitCode::FAILURE
}
}
}
入力パスに実際の DOCX ファイルを配置して、次を実行します。
PATH="$PWD/.venv/bin:$PATH" cargo run -- /absolute/path/example.docx new-pdfs
入力と new-pdfs/example.docx.pdf を示す Converted 行が表示されることを確認します。その PDF を開き、テキスト、ページ数、レイアウトを原本と比較します。%PDF- のチェックはヘッダーを検証するだけで、すべてのページや埋め込みオブジェクトが変換後も残っていることを証明するものではありません。また、LibreOffice は .docx に名前を変更したテキストを認識する場合があるため、名前を変更したファイルは、変換失敗を確実にテストする方法にはなりません。
--host-location local の要件に従い、同じファイルシステムにアクセスできる、権限を制限した同一のアカウントで CLI とサーバーを実行します。出力先のファイルシステムはハードリンクをサポートする必要があります。最終的なリンクの作成は、そのファイル名がすでに存在する場合に失敗します。
フォルダー全体の一括変換
同じ実行ファイルで、タスクを無制限に起動することなく、フォルダーを再帰せずに一括処理できます。
PATH="$PWD/.venv/bin:$PATH" cargo run -- /absolute/path/documents new-batch-pdfs
サブディレクトリ、シンボリックリンク、未対応の拡張子を無視し、対応ファイルをソート順に処理します。成功した結果を保持し、いずれかの変換が失敗した場合は異常終了します。拡張子は最初のフィルターにすぎず、ファイルが有効または安全である証拠にはなりません。ジョブの実行中は、他のプロセスに入力ディレクトリや出力ディレクトリを変更させないでください。
report.doc と report.docx に対し、別々の report.doc.pdf ファイルと report.docx.pdf ファイルが生成されることを確認します。選択した別のファイルが失敗しても、これらの成功した PDF は残ります。失敗したファイル名は stderr に表示され、バッチはステータス 1 で終了します。入力またはワーカーを修正してから、新しい出力ディレクトリに対して再試行します。古いディレクトリでコマンドを繰り返すと失敗し、その中の PDF は置き換えられません。
エラーへの適切な対処
- 入力が存在しない場合、選択対象が空の場合、出力ディレクトリがすでに存在する場合は、明示的に失敗します。
- 変換が失敗した場合、作成途中の PDF は公開されません。先行する変換が一部成功していても、バッチの非ゼロの終了ステータスを確認してください。
- サーバー側でタイムアウトすると、ワーカーは終了します。再試行前に再起動し、再試行回数には上限を設けます。
- クライアントはプロセス監視ツールではありません。CLI とその子プロセスを終了させる、ジョブ全体の期限を追加してください。クライアントだけを終了しても、LibreOffice で実行中の処理が中止されるとは限りません。
- ローカルの診断情報には、パスや文書の詳細が含まれる場合があります。変換ツールの生のエラーを Web API 経由で返さず、アクセスを制限したログに保存してください。
付属の CLI は単一のワーカーを対象とします。アプリケーションがアップロードをキューに入れる場合は、そのアプリケーションの認証とストレージチェックを経由してのみワーカーにアクセスできるようにします。XML-RPC を公開すると、呼び出し元がそれらを迂回できてしまいます。ワーカーを追加する場合は、個別の LibreOffice プロファイルと、重複しない XML-RPC/UNO のポートの組を設定し、変換ごとにサーバーを起動するのではなく、各ジョブを明示的に振り分けます。
対応形式の概要
実際の対応範囲は、インストールされている LibreOffice のコンポーネントとフィルターに依存します。まずは以下の控えめな選択範囲から始め、代表的な文書で検証してください。
| 分類 | 入力例 | この CLI の出力 |
|---|---|---|
| ワープロ文書 | DOCX, DOC, ODT, RTF, TXT | |
| スプレッドシート | XLSX, XLS, ODS, CSV | |
| プレゼンテーション | PPTX, PPT, ODP |
必要なフォントをインストールし、改ページ、数式、埋め込みオブジェクト、描画を確認します。プロセスの正常終了と %PDF- のファイルヘッダーチェックだけでは、見た目の再現性を確認することも、デジタル署名を検証することもできません。
マネージドの文書変換については、Transloadit の 🤖 /document/convert Robot を参照してください。
