第188回 受信記録だけ先に確定しない:PythonとSQLiteで作るトランザクショナルインボックス

第187回では、承認の消費と処理依頼を送信側の同じSQLiteトランザクションで確定し、アウトボックスから再送できるようにしました。受信側には、同じevent_idを重複登録しない台帳も用意しました。

ただし、受信台帳だけを先に確定し、その後で業務データを更新すると問題が残ります。台帳の確定後、業務更新の前に停止した場合、再送されたイベントを「受信済み」として読み飛ばし、処理されないままになるためです。

今回は、入荷イベントの受信記録と在庫数量の加算を、受信側にある一つのSQLiteトランザクションで確定します。同じイベントが再送された場合は、保存しておいた初回の業務結果を含む応答を返し、在庫を再加算しません。

これはシステム全体のexactly-onceを保証する実装ではありません。同じデータベース、同じevent_id、同じイベント内容という範囲で、業務更新の重複を防ぐ小さな受信処理です。

受信記録と業務更新の間を空けない

停止した場所 インボックス 在庫 再送時
トランザクション開始前 未登録 未更新 通常どおり処理する
受信記録後、コミット前 ロールバック 未更新 通常どおり処理する
在庫更新後、コミット前 ロールバック ロールバック 通常どおり処理する
コミット後、応答前 登録済み 更新済み 初回の業務結果を含む重複応答を返す

SQLiteのトランザクションに関する公式説明では、同じトランザクション内の変更は、まとめて確定するか、まとめて取り消されると説明されています。今回利用するのは、同じSQLiteデータベース内に限られるこの性質です。

今回の実行契約

項目 仕様
動作環境 Python 3.11以上、標準ライブラリ、ローカルファイルシステム。実行例ではbashを使用する
入力 標準入力からBOMなしUTF-8のJSONを最大8,192バイト読み込む
イベント event_id、event_type、sku、quantityの4項目だけを受理する
イベント種別 inventory.received.v1だけを処理する
数量 1イベントにつき1~10,000。在庫合計は2,147,483,647以下
重複 同じevent_idと同じ正規化JSONなら在庫を更新せず、初回の業務結果を含む重複応答を返す
ID競合 同じevent_idで内容が異なる場合は拒否する
書き込み競合 BEGIN IMMEDIATEを使い、SQLiteのロック待ち上限を5秒にする
ジャーナル MEMORYとOFFはプロセス停止時の安全性を満たさないため拒否する
初期化 既存SKUの数量は上書きしない
対象外 イベントの認証、通信、別DBや外部APIとの原子的な更新、イベントの順序制御

Python 3.11のsqlite3文書に従い、isolation_level=Noneで暗黙のトランザクション開始を無効にし、SQLのBEGIN IMMEDIATE、commit()、rollback()を明示的に使います。

SQLiteのjournal_modeに関する公式説明では、MEMORYとOFFはアプリケーション停止時にデータベースを破損させる可能性があるとされています。コードでは接続時に現在のモードを確認し、この2種類を終了コード78で拒否します。

受信処理を実装する

次のコードをinbox_inventory.pyとして保存します。--failpointは異常停止を確認するためのテスト専用オプションです。

from __future__ import annotations

import argparse
import hashlib
import json
import os
import re
import sqlite3
import sys
from datetime import datetime, timezone

MAX_EVENT_BYTES = 8192
MAX_STOCK = 2_147_483_647
EVENT_TYPE = "inventory.received.v1"
ID_PATTERN = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:-]{0,63}")


class AppError(Exception):
    def __init__(
        self,
        code: str,
        exit_code: int = 65,
        **details: object,
    ) -> None:
        super().__init__(code)
        self.code = code
        self.exit_code = exit_code
        self.details = details


def compact_json(value: object) -> str:
    return json.dumps(
        value,
        ensure_ascii=False,
        sort_keys=True,
        separators=(",", ":"),
    )


def emit(stream: object, value: object) -> None:
    stream.write(compact_json(value) + "\n")
    stream.flush()


class JsonArgumentParser(argparse.ArgumentParser):
    def error(self, message: str) -> None:
        emit(sys.stderr, {"error": "invalid_arguments"})
        raise SystemExit(2)


def identifier(value: str) -> str:
    if ID_PATTERN.fullmatch(value) is None:
        raise argparse.ArgumentTypeError(
            "use 1 to 64 ASCII letters, digits, dot, underscore, "
            "colon, or hyphen"
        )
    return value


def initial_quantity(value: str) -> int:
    try:
        number = int(value, 10)
    except ValueError as exc:
        raise argparse.ArgumentTypeError(
            "quantity must be an integer"
        ) from exc
    if not 0 <= number <= MAX_STOCK:
        raise argparse.ArgumentTypeError(
            f"quantity must be 0..{MAX_STOCK}"
        )
    return number


def reject_duplicate_keys(
    pairs: list[tuple[str, object]],
) -> dict[str, object]:
    result: dict[str, object] = {}
    for key, value in pairs:
        if key in result:
            raise ValueError("duplicate key")
        result[key] = value
    return result


def reject_constant(value: str) -> None:
    raise ValueError(f"unsupported constant: {value}")


def read_event() -> dict[str, object]:
    raw = sys.stdin.buffer.read(MAX_EVENT_BYTES + 1)
    if len(raw) > MAX_EVENT_BYTES:
        raise AppError(
            "event_too_large",
            max_bytes=MAX_EVENT_BYTES,
        )

    try:
        text = raw.decode("utf-8")
        value = json.loads(
            text,
            object_pairs_hook=reject_duplicate_keys,
            parse_constant=reject_constant,
        )
    except (UnicodeDecodeError, ValueError, RecursionError) as exc:
        raise AppError("invalid_json") from exc

    required = {
        "event_id",
        "event_type",
        "sku",
        "quantity",
    }
    if not isinstance(value, dict) or set(value) != required:
        raise AppError("invalid_event_shape")

    event_id = value["event_id"]
    if (
        not isinstance(event_id, str)
        or ID_PATTERN.fullmatch(event_id) is None
    ):
        raise AppError("invalid_event_id")

    if value["event_type"] != EVENT_TYPE:
        raise AppError(
            "unsupported_event_type",
            expected=EVENT_TYPE,
        )

    sku = value["sku"]
    if (
        not isinstance(sku, str)
        or ID_PATTERN.fullmatch(sku) is None
    ):
        raise AppError("invalid_sku")

    quantity = value["quantity"]
    if (
        type(quantity) is not int
        or not 1 <= quantity <= 10_000
    ):
        raise AppError(
            "invalid_quantity",
            min=1,
            max=10_000,
        )

    return value


def connect_database(path: str) -> sqlite3.Connection:
    connection = sqlite3.connect(
        path,
        timeout=5.0,
        isolation_level=None,
    )
    connection.row_factory = sqlite3.Row
    connection.execute("PRAGMA foreign_keys = ON")
    return connection


def check_journal_mode(
    connection: sqlite3.Connection,
) -> None:
    row = connection.execute("PRAGMA journal_mode").fetchone()
    if row is None:
        raise AppError("journal_mode_unavailable", exit_code=78)

    journal_mode = str(row[0]).lower()
    if journal_mode in {"memory", "off"}:
        raise AppError(
            "unsafe_journal_mode",
            exit_code=78,
            journal_mode=journal_mode,
        )


def create_schema(connection: sqlite3.Connection) -> None:
    connection.execute(
        """
        CREATE TABLE IF NOT EXISTS inventory_items (
            sku TEXT PRIMARY KEY,
            quantity INTEGER NOT NULL,
            CHECK (
                typeof(sku) = 'text'
                AND length(sku) BETWEEN 1 AND 64
            ),
            CHECK (
                typeof(quantity) = 'integer'
                AND quantity BETWEEN 0 AND 2147483647
            )
        )
        """
    )
    connection.execute(
        """
        CREATE TABLE IF NOT EXISTS inbox_events (
            event_id TEXT PRIMARY KEY,
            event_type TEXT NOT NULL,
            event_json TEXT NOT NULL,
            event_sha256 TEXT NOT NULL,
            result_json TEXT NOT NULL,
            processed_at TEXT NOT NULL,
            CHECK (length(event_id) BETWEEN 1 AND 64),
            CHECK (event_type = 'inventory.received.v1'),
            CHECK (length(event_sha256) = 64)
        )
        """
    )


def initialize(
    connection: sqlite3.Connection,
    args: argparse.Namespace,
) -> dict[str, object]:
    connection.execute("BEGIN IMMEDIATE")
    create_schema(connection)

    row = connection.execute(
        "SELECT quantity FROM inventory_items WHERE sku = ?",
        (args.sku,),
    ).fetchone()

    if row is None:
        connection.execute(
            """
            INSERT INTO inventory_items(sku, quantity)
            VALUES (?, ?)
            """,
            (args.sku, args.quantity),
        )
        created = True
        quantity = args.quantity
    else:
        created = False
        quantity = row["quantity"]

    connection.commit()
    return {
        "created": created,
        "quantity": quantity,
        "sku": args.sku,
        "status": "initialized",
    }


def process_event(
    connection: sqlite3.Connection,
    args: argparse.Namespace,
) -> dict[str, object]:
    event = read_event()
    event_json = compact_json(event)
    event_sha256 = hashlib.sha256(
        event_json.encode("utf-8")
    ).hexdigest()

    connection.execute("BEGIN IMMEDIATE")

    existing = connection.execute(
        """
        SELECT event_json, result_json
        FROM inbox_events
        WHERE event_id = ?
        """,
        (event["event_id"],),
    ).fetchone()

    if existing is not None:
        if existing["event_json"] != event_json:
            raise AppError(
                "event_id_conflict",
                event_id=event["event_id"],
            )

        original_result = json.loads(existing["result_json"])
        connection.commit()
        return {
            "event_id": event["event_id"],
            "original_result": original_result,
            "status": "already_processed",
        }

    item = connection.execute(
        "SELECT quantity FROM inventory_items WHERE sku = ?",
        (event["sku"],),
    ).fetchone()
    if item is None:
        raise AppError("unknown_sku", sku=event["sku"])

    new_quantity = item["quantity"] + event["quantity"]
    if new_quantity > MAX_STOCK:
        raise AppError(
            "stock_limit_exceeded",
            sku=event["sku"],
        )

    original_result = {
        "event_id": event["event_id"],
        "new_quantity": new_quantity,
        "quantity_added": event["quantity"],
        "sku": event["sku"],
    }
    processed_at = datetime.now(timezone.utc).isoformat(
        timespec="seconds"
    ).replace("+00:00", "Z")

    connection.execute(
        """
        INSERT INTO inbox_events(
            event_id,
            event_type,
            event_json,
            event_sha256,
            result_json,
            processed_at
        ) VALUES (?, ?, ?, ?, ?, ?)
        """,
        (
            event["event_id"],
            event["event_type"],
            event_json,
            event_sha256,
            compact_json(original_result),
            processed_at,
        ),
    )

    cursor = connection.execute(
        """
        UPDATE inventory_items
        SET quantity = ?
        WHERE sku = ?
        """,
        (new_quantity, event["sku"]),
    )
    if cursor.rowcount != 1:
        raise AppError(
            "inventory_update_failed",
            sku=event["sku"],
        )

    if args.failpoint == "before-commit":
        os.write(
            2,
            b'{"error":"failpoint_before_commit"}\n',
        )
        os._exit(90)

    connection.commit()

    if args.failpoint == "after-commit":
        os.write(
            2,
            b'{"error":"failpoint_after_commit"}\n',
        )
        os._exit(91)

    return {"status": "processed", **original_result}


def show_item(
    connection: sqlite3.Connection,
    args: argparse.Namespace,
) -> dict[str, object]:
    row = connection.execute(
        "SELECT quantity FROM inventory_items WHERE sku = ?",
        (args.sku,),
    ).fetchone()
    if row is None:
        raise AppError("unknown_sku", sku=args.sku)
    return {
        "quantity": row["quantity"],
        "sku": args.sku,
        "status": "found",
    }


def build_parser() -> argparse.ArgumentParser:
    parser = JsonArgumentParser()
    parser.add_argument("--db", required=True)
    subparsers = parser.add_subparsers(
        dest="command",
        required=True,
    )

    init_parser = subparsers.add_parser("init")
    init_parser.add_argument(
        "--sku",
        required=True,
        type=identifier,
    )
    init_parser.add_argument(
        "--quantity",
        required=True,
        type=initial_quantity,
    )

    process_parser = subparsers.add_parser("process")
    process_parser.add_argument(
        "--failpoint",
        choices=(
            "none",
            "before-commit",
            "after-commit",
        ),
        default="none",
        help=argparse.SUPPRESS,
    )

    show_parser = subparsers.add_parser("show")
    show_parser.add_argument(
        "--sku",
        required=True,
        type=identifier,
    )
    return parser


def main() -> int:
    args = build_parser().parse_args()
    connection: sqlite3.Connection | None = None

    try:
        connection = connect_database(args.db)
        check_journal_mode(connection)

        if args.command == "init":
            result = initialize(connection, args)
        elif args.command == "process":
            result = process_event(connection, args)
        else:
            result = show_item(connection, args)

        emit(sys.stdout, result)
        return 0

    except AppError as exc:
        if connection is not None and connection.in_transaction:
            connection.rollback()
        emit(
            sys.stderr,
            {"error": exc.code, **exc.details},
        )
        return exc.exit_code

    except sqlite3.OperationalError as exc:
        if connection is not None and connection.in_transaction:
            connection.rollback()
        message = str(exc).lower()
        if "locked" in message or "busy" in message:
            emit(sys.stderr, {"error": "database_busy"})
            return 75
        emit(sys.stderr, {"error": "database_error"})
        return 74

    except (
        sqlite3.DatabaseError,
        OSError,
        json.JSONDecodeError,
    ):
        if connection is not None and connection.in_transaction:
            connection.rollback()
        emit(sys.stderr, {"error": "database_error"})
        return 74

    finally:
        if connection is not None:
            connection.close()


if __name__ == "__main__":
    raise SystemExit(main())

入力JSONは、キー順と空白をそろえた本稿独自の形式へ正規化してから保存します。そのため、キー順だけが異なる再送は同じイベントとして扱われます。これは汎用的な標準JSON正規化方式ではありません。

event_sha256は調査時に内容を識別しやすくするための値です。重複判定ではハッシュだけに依存せず、保存した正規化JSON全体を比較しています。

在庫を初期化してイベントを処理する

まずテーブルを作り、SKUの初期数量を10にします。

python3 inbox_inventory.py --db receiver.db init \
  --sku SKU-001 --quantity 10
{"created":true,"quantity":10,"sku":"SKU-001","status":"initialized"}

同じSKUでもう一度initを実行しても、既存数量は変更しません。初期化コマンドを在庫の修正手段としては使わない設計です。

続いて、5個の入荷イベントを処理します。

printf '%s\n' \
  '{"event_id":"evt-001","event_type":"inventory.received.v1","sku":"SKU-001","quantity":5}' \
  | python3 inbox_inventory.py --db receiver.db process
{"event_id":"evt-001","new_quantity":15,"quantity_added":5,"sku":"SKU-001","status":"processed"}

inbox_eventsへの登録と、inventory_itemsの数量変更は、ここで一度にコミットされています。

同じイベントを再送しても再加算しない

キー順と空白を変え、同じイベントを再送します。

printf '%s\n' \
  '{ "quantity": 5, "sku": "SKU-001", "event_type": "inventory.received.v1", "event_id": "evt-001" }' \
  | python3 inbox_inventory.py --db receiver.db process
{"event_id":"evt-001","original_result":{"event_id":"evt-001","new_quantity":15,"quantity_added":5,"sku":"SKU-001"},"status":"already_processed"}

現在数量を確認しても15のままです。

python3 inbox_inventory.py --db receiver.db show --sku SKU-001
{"quantity":15,"sku":"SKU-001","status":"found"}

一方、evt-001の数量を6へ変えて再送すると、終了コード65のevent_id_conflictになります。同じIDへ異なる内容を割り当てる不整合を、処理済みとして隠さないためです。

コミット前の停止を再現する

次は、受信記録と在庫更新を実行した後、コミット直前にプロセスを終了させます。

printf '%s\n' \
  '{"event_id":"evt-002","event_type":"inventory.received.v1","sku":"SKU-001","quantity":7}' \
  | python3 inbox_inventory.py --db receiver.db process \
      --failpoint before-commit
echo "$?"
{"error":"failpoint_before_commit"}
90

この時点では、インボックス登録と在庫更新のどちらも確定していません。在庫は15のままです。

python3 inbox_inventory.py --db receiver.db show --sku SKU-001
{"quantity":15,"sku":"SKU-001","status":"found"}

--failpointを外して同じイベントを再送すると、初回処理として受理され、数量は22になります。

printf '%s\n' \
  '{"event_id":"evt-002","event_type":"inventory.received.v1","sku":"SKU-001","quantity":7}' \
  | python3 inbox_inventory.py --db receiver.db process
{"event_id":"evt-002","new_quantity":22,"quantity_added":7,"sku":"SKU-001","status":"processed"}

コミット後の応答消失を再現する

今度はコミット後、通常の成功JSONを返す前に終了させます。

printf '%s\n' \
  '{"event_id":"evt-003","event_type":"inventory.received.v1","sku":"SKU-001","quantity":3}' \
  | python3 inbox_inventory.py --db receiver.db process \
      --failpoint after-commit
echo "$?"
{"error":"failpoint_after_commit"}
91

テスト用の標準エラーには停止位置が表示されますが、通常の成功応答は返りません。実際の通信断では、呼び出し側はコミットの成否を応答だけでは判断できません。一方、DBでは受信記録と在庫数量25が確定しています。同じイベントを再送すると、再加算せずに初回の業務結果を含む重複応答を返します。

printf '%s\n' \
  '{"event_id":"evt-003","event_type":"inventory.received.v1","sku":"SKU-001","quantity":3}' \
  | python3 inbox_inventory.py --db receiver.db process
{"event_id":"evt-003","original_result":{"event_id":"evt-003","new_quantity":25,"quantity_added":3,"sku":"SKU-001"},"status":"already_processed"}

配送側は、応答を受け取れなかった場合でもevent_idを作り直さず、同じイベントを再送する必要があります。

終了コードを呼び出し側の判断に使う

終了コード 意味 呼び出し側の扱い
0 処理、重複確認、初期化、参照の成功 標準出力のstatusを確認する
2 コマンドライン引数が不正 設定を修正する
65 JSON、イベント内容、SKU、ID競合などの入力エラー 同じ内容を無条件に再試行しない
74 DBファイルやSQLiteの入出力エラー 保存先とDB状態を調査する
75 SQLiteがロック競合を報告 上限を決めて同じイベントを再試行できる
78 安全でない、または取得できないジャーナル設定 DB設定を確認し、処理を開始しない
90、91 テスト用failpoint 通常運用では指定しない

BEGIN IMMEDIATEは、重複確認より前に書き込みトランザクションを開始します。複数プロセスが同じDBへ同時に書き込む場合、後から来た処理は待機し、先行処理のコミット後に受信記録を再確認します。ロック待ちが5秒の上限を超えると終了コード75です。SQLiteのトランザクション仕様にあるとおり、SQLiteでは同時に複数の書き込みトランザクションを進められません。トランザクション内で時間のかかる通信や対話処理は行わないようにします。

この実装で防げない重複を確認する

  • 同じ入荷へ異なるevent_idを付ければ、それぞれ別のイベントとして加算されます。
  • インボックス行を削除した後に古いイベントを再送すると、再び処理されます。
  • DBを過去のバックアップへ戻すと、それ以降の受信記録と在庫更新も戻ります。
  • 別DBの更新、メール送信、外部API呼び出しは、このSQLiteトランザクションへ含められません。
  • event_idは送信者の身元を証明しません。信頼できない入力を受ける場合は、認証や署名検証を受信処理の前に追加する必要があります。
  • 今回のfailpointが再現するのはプロセス停止です。OS停止、電源断、ストレージ障害の検証を代替するものではありません。

実運用では、送信側アウトボックスが発行した安定したevent_idをそのまま再送し、インボックスの保持期間を再送可能期間より短くしないことが重要です。同じ業務を異なるイベントIDで登録する可能性がある場合は、入荷伝票番号などの業務キーにも一意制約を設けます。

送信側のアウトボックスと今回のインボックスを組み合わせると、配送そのものは繰り返されても、同じイベントによる受信側のDB更新は繰り返さない構成になります。その適用範囲を「同じイベントIDと同じ受信DB」に限定して理解することが、過大なexactly-onceの主張を避けるポイントです。