Rustにおける厳密に単調なタイムスタンプとギャップレスシーケンス
Strictly monotonic timestamps and gapless sequences in Rust (tsoracle.rs)
要約
tsoracleは、分散システムにおいて厳密に単調なタイムスタンプとギャップレスシーケンスを生成するためのRustライブラリです。これは、データベースのMVCC、複数シャードからの変更データのマージ、監査ログの維持などに役立ちます。主な特徴として、単調性、ギャップレス性、クラッシュ安全性、およびプラグ可能なコンセンサスドライバが挙げられます。
全文翻訳
tsoracle — Rustにおける単調タイムスタンプとギャップレスシーケンス
tsoracle
Rustにおける厳密に単調なタイムスタンプとギャップレスシーケンス。
分散 · 高可用性 · 耐障害性 · 組み込み可能
$ cargo install tsoracle
$ tsoracle
── TSOとは? ──
タイムスタンプオラクル(TSO)は、分散システム全体でイベントを順序付ける、厳密に増加する整数IDを発行するサービスです。MVCCを持つデータベースの構築、多数のシャードからの変更データのマージ、またはマシン間の実際の発生順序関係を持つ監査ログの維持を行う際に必要となります。
ホストごとのウォールクロックは、単調性を保つには十分ではありません。データベースシーケンスはシャードを跨いでスケールしません。TSOは標準的な解決策であり、Spanner、CockroachDB、FoundationDBなどが内部で使用しています。
tsoracleはさらに一歩進んでいます。同じエンジンがギャップレスシーケンスも発行します。タイムスタンプは順序付けされていればよいのに対し、シーケンスは連続している必要があります — …, 41, 42, 43, … のように何もスキップされない状態です。これは、代理キー、請求書番号、注文番号、または元帳の行番号にまさに望ましいものです。1回のラウンドトリップで、名前付きキーごとに1つの永続的なカウンターが提供され、クラッシュやフェイルオーバーを跨いでも穴が開くことはありません。get_ts()の代わりにget_seq()を呼び出します。
→ Read: Why distributed systems need a TSO · Gapless sequences with GetSeq
── 特徴 ──
厳密に単調
発行されるすべてのタイムスタンプは、それ以前のすべてのタイムスタンプよりも厳密に大きくなります。重複や後退はありません。
ギャップレスシーケンス
順序付けられたIDだけでなく、連続したIDが必要ですか? get_seq()は、名前付きキーごとに密でギャップのないブロックを発行します — 何もスキップされず、クラッシュやフェイルオーバーを跨いで再利用されることはありません。
クラッシュセーフ
ウィンドウの状態は、そこからのタイムスタンプが発行される前にfsyncされます。再起動しても巻き戻ることはありません。
プラグ可能なコンセンサス
本番環境用のopenraftおよびOmniPaxosドライバが含まれています。raft-rs、etcd、または独自のレプリケートログでtsoracleをバックエンド化するための1つのトレイトです。
gRPCクライアントが含まれています
リーダー検出、リクエストの集約、再接続 — これらすべてが処理されます。get_ts()またはget_seq()を呼び出すだけです。
運用メトリクス
アロケータ、リーダー、リクエストのメトリクスがmetricsファサードを通じて発行されます。Prometheus対応です。
組み込み可能
スタンドアロンCLIを実行するか、数行のRustコードでtsoracle-serverを独自のバイナリに組み込みます。
── 仕組み ──
client → leader → followers
1回のラウンドトリップでN個のIDのバッチが割り当てられます。
リーダーは新しいハイウォーターマークをfsyncし、その範囲がプロセスを離れる前にraftを通じてレプリケートします。クライアントはローカルでバッチからIDを発行します — コモディティハードウェアで毎秒数百万件です。
get_seq()は同じパスを通り、ギャップレスIDを発行します。リーダーは名前付きキーごとの永続的なカウンターを進め、その更新をfsyncしてレプリケートし、連続したブロックを返します。唯一の違いは、ギャップレスの更新は「消費済み」としてマークできないため、呼び出しは冪等ではないということです — 不明瞭な失敗はSeqUncertainとして表面化され、サイレントに再試行されることはありません。
→ Read the architecture summary
── 入手方法 ──
スタンドアロンバイナリ
$ cargo install tsoracle
$ tsoracle
# 127.0.0.1:50551 でリッスンします
# 状態を ./tsoracle-data/ に永続化します
# 単純な `tsoracle` は `tsoracle serve file` のショートカットです。
独自のバイナリに組み込む
use tsoracle_server::Server;
use tsoracle_driver_file::FileDriver;
let driver = FileDriver::open_or_init("./data")?;
let server = Server::builder()
.consensus_driver(driver)
.build()?;
server.serve_with_shutdown(addr, shutdown).await?;
組み込みパスは、プロセス内のライブラリとしてtsoracle-serverを実行します。実行可能なバージョンについては、embedded-server exampleを参照してください。
その他の配布チャネル:GitHub Releasesのソースリリースと変更ログ、crates.ioで公開されているRustクレート、ghcr.io/prisma-risk/tsoracleのコンテナイメージ、およびghcr.io/prisma-risk/chartsのHelmチャートです。完全なソースツリーは、Apache-2.0ライセンスの下でgithub.com/prisma-risk/tsoracleにあります。
── 強度向上 ──
tsoracleは、そのpostcardデコーダーに対するカバレッジ誘導ファジング、ストレージおよびレプリケーションパスに対するfailpoint駆動クラッシュテスト、そしてopenraftおよびOmniPaxosバックエンドの両方をカバーするインプロセス+マルチプロセスのストレスハーネスでテストされています。ファズハーネスは夜間に実行されます。ストレスハーネスはすべてのPRで実行されます。
詳細: crates/tsoracle-tests · fuzz/
── フィードバックとバグレポート ──
バグレポートと機能提案はGitHubのイシューで追跡されます。報告内容に合ったテンプレートを選択してください:
- Bug report — 具体的な再現手順がある欠陥の場合。テンプレートがトレース、影響を受けた行、および現在失敗している回帰テストを案内します。
- Work scope — 明確なスコープと完了基準を持つ機能強化または任意の限定的な変更(ドキュメント、リファクタリング、新しいコンポーネント、強度向上)の場合。
既存のレポートはgithub.com/prisma-risk/tsoracle/issuesで閲覧できます。空のイシューは無効です — トリアージを迅速に進めるために、テンプレートを使用してください。
セキュリティ脆弱性は別途、プライベートなパスに従います。公開イシューを開かないでください。代わりにdraft security advisoryを開いてください。24時間以内に確認し、72時間以内にトリアージし、30日以内に開示を調整します。完全なポリシーはSECURITY.mdに記載されています。
── 貢献 ──
貢献は歓迎されます — 1行の明確化から新しいConsensusDriverの実装まで。最も有用な変更は、tsoracleの実際の使用に基づいています。デプロイメントで遭遇したバグ、不足している運用フック、ドキュメントのギャップを埋める例などです。数行を超えるものについては、まずイシューを開いてください — コードの前にスコープを合わせる方が、レビューでの再設計よりも迅速です。議論はイシュー自体で行われ、別途フォーラムやチャットはありません。
コントリビューターガイド — ローカルセットアップ、PRにCIが実行するチェック、パニックポリシー、リリースフロー — はCONTRIBUTING.mdにあります。要約すると:
- Rustツールチェーンは
rust-toolchain.tomlで固定されています — 任意のcargoコマンドで適切なバージョンがインストールされます。また、protoおよびRocksDBビルドのためにprotocとLLVM/Clang(libclang)も必要です。 - プッシュする前にCIに合わせます:
cargo fmt --all -- --check、cargo clippy --workspace --all-targets --all-features -- -D warnings、cargo test --workspace --all-features。追跡されたプリコミットフックが最初の2つを自動的に実行します。 - コミットメッセージはConventional Commits(
feat:、fix:、chore:など)に従います — このプレフィックスがrelease-plzでのクレートごとのsemverバンプを駆動します。
どこから始めますか? good first issueおよびhelp wantedラベルは、新規コントリビューター向けにスコープが設定され、よく説明されたイシューをリストしています。
── 最近の投稿 ──
-
Why distributed systems need a timestamp oracle
12分読了
タイムスタンプオラクルは、分散システム全体でイベントを順序付ける厳密に増加するIDを発行します。マシン間の順序付けがなぜ難しいのか、そしてTSOが何を解決するのか。
-
10分読了
タイムスタンプオラクルは厳密なグローバル単調性を提供します。UUIDv7はローカルでk-sortable IDを提供します。それぞれがいつ正しいのか、そしてUUIDv7がサイレントに失敗する場所。
-
Gapless sequences: GetSeq alongside GetTs
9分読了
tsoracleは現在、2種類の厳密に順序付けられた整数を発行しています:単調タイムスタンプとギャップレスで密なシーケンス。ギャップレス性のコスト、GetSeqが冪等でない理由、そしていつそれを使用すべきか。
── ドキュメント ──
How tsoracle works — このサイトのアーキテクチャ概要。
DeepWiki — ウィンドウアロケータ、ConsensusDriver契約、および運用トピック(fsyncコスト、リーダーハンドオフ、デプロイメントトポロジー)をカバーするプロセドキュメント。
docs.rs/tsoracle-server — 生成されたAPIリファレンス。