第187回 承認消費と処理依頼を同時に残す:PythonとSQLiteで作るトランザクショナルアウトボックス

第186回では、検証済みの承認IDをSQLiteへ予約してから子コマンドを起動しました。この順番なら、同じ台帳に対する同じ承認IDによる二重起動は防げます。ただし、予約の確定後に停止すると、子処理を起動していなくても承認は消費済みになります。

今回は、承認の消費と処理依頼の作成を、同じSQLiteトランザクションで確定します。処理依頼はアウトボックスへ残し、別の配送処理から受信側へ再送できるようにします。

受信側では、同じevent_idを一度だけ登録します。配送後、送信側の完了記録前に停止しても、再送されたイベントを重複として受理できます。

これは、システム全体のexactly-onceを保証する仕組みではありません。実装するのは、承認消費と同じコミットで送信側DBへ処理依頼を残すことと、同じイベントを重複登録しない受信台帳です。

承認消費と実行を直接つながない

停止した場所 送信側 受信側 再開方法
送信側のコミット前 承認利用とアウトボックスのどちらも残らない 未受信 承認検証からやり直す
送信側のコミット後、配送前 未配送のイベントが残る 未受信 配送処理を実行する
受信側のコミット後、送信側の完了記録前 未配送に見える 受信済み 同じイベントを再送し、重複として確認する
送信側の完了記録後 配送済み 受信済み 次回の配送対象にはならない。ただし、すでに選択済みの並行処理が再送する場合はある

アウトボックスが防ぐのは、承認だけを消費して処理依頼を残せない状態です。配送処理の定期実行や、受信後の実処理までは用意しません。

今回の実行契約

項目 仕様
動作環境 Python 3.11以上、標準ライブラリのsqlite3、ローカルファイルシステム
送信側DB source.db。承認利用とアウトボックスを同じトランザクションで記録する
受信側DB sink.db。event_idを主キーにして重複登録を防ぐ
ID 1~64文字。先頭はASCII英数字、2文字目以降はASCII英数字、ピリオド、アンダースコア、ハイフン
メッセージ UTF-8で1~4096バイト
配送単位 未配送イベントを作成順に1件処理する
標準出力 成功時に1行JSONを出力する
標準エラー出力 業務上の拒否、保存エラー、停止再現時に1行JSONを出力する
対象外 署名、期限、取消の検証、実際の通知や外部API呼び出し、定期実行

掲載例のenqueueは、形式が正しい承認IDなら受け取ります。実運用では、第186回までの検証を通った承認IDだけを、同じ信頼境界内から渡してください。誰でも実行できるCLIとして公開すると、承認検証を迂回できます。

BEGIN IMMEDIATEは書き込みトランザクションを先に開始します。同じDBへ別の書き込みがある場合は待機し、設定時間内に取得できなければロックエラーになります。二つのDBを一つのトランザクションへまとめるものではありません。

アウトボックスと重複を防ぐ受信台帳を実装する

次のコードをoutbox_demo.pyとして、source.dbとsink.dbがない作業ディレクトリへ保存します。

#!/usr/bin/env python3
import argparse
import hashlib
import json
import re
import sqlite3
import sys
from contextlib import closing, contextmanager
from datetime import datetime, timezone
from pathlib import Path

SOURCE_DB = Path('source.db')
SINK_DB = Path('sink.db')
ID_RE = re.compile(r'[A-Za-z0-9][A-Za-z0-9._-]{0,63}')

SOURCE_SCHEMA = '''
BEGIN IMMEDIATE;
CREATE TABLE outbox (
    outbox_id INTEGER PRIMARY KEY,
    event_id TEXT NOT NULL UNIQUE,
    payload_json TEXT NOT NULL,
    created_at TEXT NOT NULL,
    delivered_at TEXT
);
CREATE TABLE approval_uses (
    approval_id TEXT PRIMARY KEY,
    event_id TEXT NOT NULL UNIQUE,
    consumed_at TEXT NOT NULL,
    FOREIGN KEY (event_id) REFERENCES outbox(event_id)
);
COMMIT;
'''

SINK_SCHEMA = '''
BEGIN IMMEDIATE;
CREATE TABLE received_events (
    event_id TEXT PRIMARY KEY,
    payload_sha256 TEXT NOT NULL,
    payload_json TEXT NOT NULL,
    received_at TEXT NOT NULL
);
COMMIT;
'''


class AppError(Exception):
    def __init__(self, kind, message, exit_code):
        super().__init__(message)
        self.kind = kind
        self.message = message
        self.exit_code = exit_code


def emit(data, stream=sys.stdout):
    print(
        json.dumps(
            data,
            ensure_ascii=False,
            sort_keys=True,
            separators=(',', ':'),
        ),
        file=stream,
    )


def utc_now():
    return datetime.now(timezone.utc).isoformat(
        timespec='seconds'
    ).replace('+00:00', 'Z')


def validate_id(value, field):
    if not isinstance(value, str) or ID_RE.fullmatch(value) is None:
        raise AppError(
            'invalid_input',
            f'{field} must start with an ASCII alphanumeric and contain only permitted characters',
            2,
        )
    return value


def validate_message(value):
    if not isinstance(value, str):
        raise AppError('invalid_input', 'message must be text', 2)
    try:
        size = len(value.encode('utf-8'))
    except UnicodeEncodeError as exc:
        raise AppError(
            'invalid_input',
            'message must be valid UTF-8 text',
            2,
        ) from exc
    if not 1 <= size <= 4096:
        raise AppError(
            'invalid_input',
            'message must be 1-4096 UTF-8 bytes',
            2,
        )
    return value


def canonical_payload(event_id, message):
    data = {
        'event_id': validate_id(event_id, 'event_id'),
        'message': validate_message(message),
        'type': 'work.requested',
    }
    return json.dumps(
        data,
        ensure_ascii=False,
        sort_keys=True,
        separators=(',', ':'),
    )


def payload_digest(event_id, payload_json):
    if not isinstance(event_id, str) or ID_RE.fullmatch(event_id) is None:
        raise AppError('invalid_stored_event', 'stored event_id is invalid', 4)
    if not isinstance(payload_json, str):
        raise AppError('invalid_stored_event', 'payload is not text', 4)

    try:
        raw = payload_json.encode('utf-8')
    except UnicodeEncodeError as exc:
        raise AppError(
            'invalid_stored_event',
            'payload is not valid UTF-8 text',
            4,
        ) from exc
    if len(raw) > 32768:
        raise AppError('invalid_stored_event', 'payload is too large', 4)

    try:
        data = json.loads(payload_json)
    except json.JSONDecodeError as exc:
        raise AppError(
            'invalid_stored_event',
            f'payload is invalid JSON: {exc.msg}',
            4,
        ) from exc

    required = {'event_id', 'message', 'type'}
    if not isinstance(data, dict) or set(data) != required:
        raise AppError(
            'invalid_stored_event',
            'payload fields are invalid',
            4,
        )
    if data['event_id'] != event_id or data['type'] != 'work.requested':
        raise AppError(
            'invalid_stored_event',
            'payload identity does not match the outbox row',
            4,
        )
    if not isinstance(data['message'], str):
        raise AppError('invalid_stored_event', 'stored message is invalid', 4)
    try:
        message_size = len(data['message'].encode('utf-8'))
    except UnicodeEncodeError as exc:
        raise AppError(
            'invalid_stored_event',
            'stored message is invalid',
            4,
        ) from exc
    if not 1 <= message_size <= 4096:
        raise AppError('invalid_stored_event', 'stored message is invalid', 4)

    expected = json.dumps(
        data,
        ensure_ascii=False,
        sort_keys=True,
        separators=(',', ':'),
    )
    if expected != payload_json:
        raise AppError(
            'invalid_stored_event',
            'payload is not in canonical form',
            4,
        )

    return hashlib.sha256(raw).hexdigest()


def open_database(path):
    if not path.is_file():
        raise AppError('database_not_found', f'{path} does not exist', 3)
    conn = sqlite3.connect(path, timeout=5, isolation_level=None)
    conn.execute('PRAGMA foreign_keys = ON')
    conn.execute('PRAGMA busy_timeout = 5000')
    return conn


@contextmanager
def immediate_transaction(conn):
    conn.execute('BEGIN IMMEDIATE')
    try:
        yield
        conn.commit()
    except BaseException:
        if conn.in_transaction:
            conn.rollback()
        raise


def create_database(path, schema):
    if path.exists():
        raise AppError('database_exists', f'{path} already exists', 4)
    conn = sqlite3.connect(path, timeout=5, isolation_level=None)
    try:
        conn.execute('PRAGMA foreign_keys = ON')
        conn.executescript(schema)
    except BaseException:
        if conn.in_transaction:
            conn.rollback()
        raise
    finally:
        conn.close()


def cmd_init_source(args):
    create_database(SOURCE_DB, SOURCE_SCHEMA)
    emit({'database': str(SOURCE_DB), 'status': 'initialized'})
    return 0


def cmd_init_sink(args):
    create_database(SINK_DB, SINK_SCHEMA)
    emit({'database': str(SINK_DB), 'status': 'initialized'})
    return 0


def cmd_enqueue(args):
    approval_id = validate_id(args.approval_id, 'approval_id')
    event_id = validate_id(args.event_id, 'event_id')
    payload_json = canonical_payload(event_id, args.message)
    now = utc_now()

    with closing(open_database(SOURCE_DB)) as conn:
        with immediate_transaction(conn):
            if conn.execute(
                'SELECT 1 FROM approval_uses WHERE approval_id = ?',
                (approval_id,),
            ).fetchone() is not None:
                raise AppError(
                    'approval_already_used',
                    'approval_id is already present',
                    4,
                )

            if conn.execute(
                'SELECT 1 FROM outbox WHERE event_id = ?',
                (event_id,),
            ).fetchone() is not None:
                raise AppError(
                    'event_already_exists',
                    'event_id is already present',
                    4,
                )

            conn.execute(
                '''INSERT INTO outbox
                   (event_id, payload_json, created_at, delivered_at)
                   VALUES (?, ?, ?, NULL)''',
                (event_id, payload_json, now),
            )
            conn.execute(
                '''INSERT INTO approval_uses
                   (approval_id, event_id, consumed_at)
                   VALUES (?, ?, ?)''',
                (approval_id, event_id, now),
            )

    emit(
        {
            'approval_id': approval_id,
            'event_id': event_id,
            'status': 'enqueued',
        }
    )
    return 0


def deliver_to_sink(event_id, payload_json):
    digest = payload_digest(event_id, payload_json)

    with closing(open_database(SINK_DB)) as conn:
        with immediate_transaction(conn):
            row = conn.execute(
                '''SELECT payload_sha256, payload_json
                   FROM received_events
                   WHERE event_id = ?''',
                (event_id,),
            ).fetchone()

            if row is None:
                conn.execute(
                    '''INSERT INTO received_events
                       (event_id, payload_sha256, payload_json, received_at)
                       VALUES (?, ?, ?, ?)''',
                    (event_id, digest, payload_json, utc_now()),
                )
                result = 'accepted'
            elif row == (digest, payload_json):
                result = 'duplicate'
            else:
                raise AppError(
                    'receiver_event_conflict',
                    'event_id already has a different payload',
                    4,
                )

    return result


def cmd_dispatch(args):
    with closing(open_database(SOURCE_DB)) as conn:
        row = conn.execute(
            '''SELECT event_id, payload_json
               FROM outbox
               WHERE delivered_at IS NULL
               ORDER BY outbox_id
               LIMIT 1'''
        ).fetchone()

    if row is None:
        emit({'status': 'idle'})
        return 0

    event_id, payload_json = row
    receiver_status = deliver_to_sink(event_id, payload_json)

    if args.simulate_crash_after_delivery:
        emit(
            {
                'event_id': event_id,
                'receiver_status': receiver_status,
                'status': 'simulated_crash_after_delivery',
            },
            stream=sys.stderr,
        )
        return 75

    with closing(open_database(SOURCE_DB)) as conn:
        with immediate_transaction(conn):
            current = conn.execute(
                '''SELECT payload_json, delivered_at
                   FROM outbox
                   WHERE event_id = ?''',
                (event_id,),
            ).fetchone()

            if current is None or current[0] != payload_json:
                raise AppError(
                    'source_event_changed',
                    'source event changed after receiver acceptance',
                    4,
                )

            if current[1] is None:
                conn.execute(
                    '''UPDATE outbox
                       SET delivered_at = ?
                       WHERE event_id = ?''',
                    (utc_now(), event_id),
                )
                status = 'delivered'
            else:
                status = 'already_delivered'

    emit(
        {
            'event_id': event_id,
            'receiver_status': receiver_status,
            'status': status,
        }
    )
    return 0


def cmd_status(args):
    with closing(open_database(SOURCE_DB)) as conn:
        approvals = [
            {'approval_id': row[0], 'event_id': row[1]}
            for row in conn.execute(
                '''SELECT approval_id, event_id
                   FROM approval_uses
                   ORDER BY approval_id'''
            )
        ]
        outbox = [
            {'event_id': row[0], 'delivered': row[1] is not None}
            for row in conn.execute(
                '''SELECT event_id, delivered_at
                   FROM outbox
                   ORDER BY outbox_id'''
            )
        ]

    with closing(open_database(SINK_DB)) as conn:
        received = [
            {'event_id': row[0]}
            for row in conn.execute(
                '''SELECT event_id
                   FROM received_events
                   ORDER BY event_id'''
            )
        ]

    emit(
        {
            'approval_uses': approvals,
            'outbox': outbox,
            'received_events': received,
            'status': 'ok',
        }
    )
    return 0


def build_parser():
    parser = argparse.ArgumentParser()
    subparsers = parser.add_subparsers(dest='command', required=True)

    subparsers.add_parser('init-source').set_defaults(func=cmd_init_source)
    subparsers.add_parser('init-sink').set_defaults(func=cmd_init_sink)

    enqueue = subparsers.add_parser('enqueue')
    enqueue.add_argument('--approval-id', required=True)
    enqueue.add_argument('--event-id', required=True)
    enqueue.add_argument('--message', required=True)
    enqueue.set_defaults(func=cmd_enqueue)

    dispatch = subparsers.add_parser('dispatch')
    dispatch.add_argument(
        '--simulate-crash-after-delivery',
        action='store_true',
    )
    dispatch.set_defaults(func=cmd_dispatch)

    subparsers.add_parser('status').set_defaults(func=cmd_status)
    return parser


def main():
    args = build_parser().parse_args()
    try:
        return args.func(args)
    except AppError as exc:
        emit(
            {
                'error': exc.kind,
                'message': exc.message,
                'status': 'error',
            },
            stream=sys.stderr,
        )
        return exc.exit_code
    except KeyboardInterrupt:
        emit(
            {'error': 'interrupted', 'status': 'error'},
            stream=sys.stderr,
        )
        return 130
    except (sqlite3.Error, OSError) as exc:
        emit(
            {
                'error': 'storage_error',
                'message': str(exc),
                'status': 'error',
            },
            stream=sys.stderr,
        )
        return 3


if __name__ == '__main__':
    sys.exit(main())

1.二つの台帳を初期化する

空の作業ディレクトリで、送信側と受信側を個別に初期化します。既存ファイルは上書きしません。

python3 outbox_demo.py init-source
python3 outbox_demo.py init-sink

それぞれ終了コード0となり、次の形式で出力されます。

{"database":"source.db","status":"initialized"}
{"database":"sink.db","status":"initialized"}

初期化に失敗すると、空または不完全なDBファイルが残る場合があります。再実行前にエラー原因とファイルの内容を確認してください。

2.承認消費と処理依頼を同時に確定する

python3 outbox_demo.py enqueue \
  --approval-id approval-187-001 \
  --event-id event-187-001 \
  --message '月次レポートの確認依頼'

成功時は次の1行JSONが標準出力へ出ます。

{"approval_id":"approval-187-001","event_id":"event-187-001","status":"enqueued"}

approval_usesとoutboxへの追加は、一つのBEGIN IMMEDIATE内で行われます。途中で例外が起きると両方をロールバックするため、通常のトランザクション処理で片方だけが確定することはありません。

コミット後、応答を受け取る前に呼び出し元が停止した場合、同じ承認IDで再登録すると終了コード4になります。新しいイベントを作らず、statusで既存状態を確認します。

3.受信後、完了記録前の停止を再現する

次のオプションは、受信側へコミットした直後に送信側のdelivered_atを更新せず、終了コード75で終了します。本物のプロセスクラッシュではありませんが、DBに残る状態は同じです。

python3 outbox_demo.py dispatch --simulate-crash-after-delivery
echo $?

標準エラー出力と終了コードは次のようになります。

{"event_id":"event-187-001","receiver_status":"accepted","status":"simulated_crash_after_delivery"}
75

状態を確認します。

python3 outbox_demo.py status
{"approval_uses":[{"approval_id":"approval-187-001","event_id":"event-187-001"}],"outbox":[{"delivered":false,"event_id":"event-187-001"}],"received_events":[{"event_id":"event-187-001"}],"status":"ok"}

送信側は未配送ですが、受信側にはイベントが存在します。この不一致を、二つのDBをまたぐ一つのトランザクションで隠そうとはしません。

4.同じイベントIDで再送する

python3 outbox_demo.py dispatch

受信側は、同じIDと同じペイロードをduplicateとして扱います。その後、送信側を配送済みに更新します。

{"event_id":"event-187-001","receiver_status":"duplicate","status":"delivered"}

もう一度dispatchを実行すると、未配送イベントがないため次の結果になります。

{"status":"idle"}

同じ承認を別イベントへ使わない

消費済みの承認IDで新しいイベントを登録すると、トランザクション内の事前確認で拒否します。

python3 outbox_demo.py enqueue \
  --approval-id approval-187-001 \
  --event-id event-187-002 \
  --message '別の処理依頼'
echo $?
{"error":"approval_already_used","message":"approval_id is already present","status":"error"}
4

別の承認IDへ既存のイベントIDを割り当てる操作も、event_already_existsで拒否します。事前確認とDBの一意制約があるため、並行実行時にも同じ承認IDやイベントIDを複数行へ登録できません。

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

終了コード 意味 呼び出し側の対応
0 初期化、登録、配送、状態表示、または配送対象なし JSONのstatusを確認する
2 IDやメッセージの入力違反 入力を修正する
3 DB不在、ロックの時間切れ、入出力などの保存エラー ファイルと実行環境を点検する
4 初期化対象DBの存在、承認やイベントの重複、イベント内容の衝突や変更、保存済みイベントの異常 自動的に別IDへ変えず、台帳を確認する
75 受信後停止の再現 同じイベントを再配送する
130 キーボード割り込み 状態を確認してから再実行する

argparseが検出するコマンド構文の誤りは、使用方法を標準エラー出力へ表示して終了コード2になります。この場合は1行JSONではありません。

実処理へ接続するときの制約

  • event_idは再送のたびに作り直さず、同じ業務処理では同じ値を使います。
  • 受信側は、同じIDなら無条件に成功扱いせず、ペイロードも一致するか確認します。本稿ではSHA-256と元のJSONを両方比較しています。
  • 複数の配送処理が同時に同じイベントを選ぶ可能性があります。受信側の主キー制約により受信行は一つになりますが、配送試行そのものは重複します。
  • statusは二つのDBを別々に読みます。実行中の配送と重なれば、システム全体の同一時点を表すスナップショットにはなりません。
  • SQLiteファイルを書き換えられる利用者は、台帳も変更できます。ファイル所有者と権限を分け、信頼できない共有ディレクトリへ置かないことが前提です。
  • ネットワークファイルシステムや複製されたDBは、この例の対象外です。利用環境でSQLiteのロックと永続化の条件を確認してください。

受信後にメール送信や外部API更新を追加する場合、受信行の一意制約だけでは副作用が一度になるとは限りません。外部処理の完了後、結果を記録する前に停止すれば、副作用が重複する余地があります。

実処理側にも同じevent_idによる重複防止がある場合は、そのキーを引き継ぎます。重複防止を利用できない処理では、再送による重複を許容するか、結果を人が照合する手順が必要です。

今回の到達点

承認消費とアウトボックス追加を同じSQLiteトランザクションへ入れることで、承認だけを消費して処理依頼を失う状態を避けられました。配送後の停止はなくせませんが、未配送イベントを残し、同じイベントIDで再送できます。

送信側では承認消費と依頼作成を同時に確定し、受信側ではIDを重複登録しません。実際の副作用については、その処理に合った重複防止を別に設計します。