第190回 欠番が埋まったら保留分を順に適用する:PythonとSQLiteで作る並べ替えバッファ

第189回では、商品ごとの連番を照合し、期待する次の連番より先のイベントをsequence_gapとして拒否しました。しかし、配送処理が並行していると、正しいイベントでも順番が入れ替わって届くことがあります。

今回は、現在値から一定範囲内の未来イベントをSQLiteへ保留します。欠けていた連番が届いたら、そこから途切れずに並んでいるイベントだけを同じトランザクションで適用します。

対象は、商品ごとの在庫を絶対数量で置き換えるイベントです。欠番の自動取得、保留時間の監視、イベント履歴の削除までは実装しません。

受信順と適用順を分ける

最後に適用した連番が10の場合、判定は次のようになります。

受信内容 応答 状態の変化
連番11 applied 連番11を適用する
連番13 buffered 保存するが、現在値は連番10のまま
連番13の保留後に連番12 applied 連番12、13の順で適用する
同じevent_id、同じ内容 duplicate 再適用しない
同じevent_id、異なる内容 event_id_conflict 保存しない
同じ商品・連番、別のイベントID sequence_conflict 保存しない
現在値より1000を超えて先の連番 sequence_too_far 保存しない

bufferedは受信失敗ではありません。イベントはデータベースへ保存済みなので、配送側は成功として扱えます。欠番を回収する処理は別途必要です。

今回の実行契約

項目 仕様
動作環境 Python 3.11以上、標準ライブラリのsqlite3、同一ホスト上のローカルファイルシステム
イベント入力 標準入力から4096バイト以内のUTF-8 JSONを1件読む
必須項目 event_id、sku、sequence、quantityの4項目だけ
event_id ASCII英数字で始まる1〜64文字。2文字目以降にはASCII英数字、ピリオド、アンダースコア、コロン、ハイフンを使用できる
sku ASCII英数字で始まる1〜64文字。2文字目以降にはASCII英数字、ピリオド、アンダースコア、ハイフンを使用できる
連番 商品ごとに1から開始し、同じ発行元が1ずつ増やす。上限は9,223,372,036,854,775,807
数量 0以上1,000,000,000以下の絶対数量
先読み範囲 last_applied_sequence + 1000まで
成功出力 標準出力へ1行JSON、終了コード0
処理開始後の失敗出力 標準エラー出力へ1行JSON。引数解析の失敗は使用方法を表示する

初期状態のlast_applied_sequence=0とquantity=0は、連番1をまだ受け取っていないことを表す初期値です。在庫数量として利用する側は、連番が1以上になったことも確認します。上限の連番を適用した後は、次に受理できる連番がないため、next_expected_sequenceをnullにします。

並べ替えバッファを実装する

次の内容をsequence_buffer.pyとして保存します。外部ライブラリは使いません。

#!/usr/bin/env python3
import argparse, hashlib, json, re, sqlite3, sys
from pathlib import Path

MAX_INPUT = 4096
MAX_AHEAD = 1000
MAX_QUANTITY = 1_000_000_000
MAX_SEQUENCE = 9_223_372_036_854_775_807
FIELDS = {'event_id', 'sku', 'sequence', 'quantity'}
EVENT_ID_RE = re.compile(r'[A-Za-z0-9][A-Za-z0-9._:-]{0,63}\Z')
SKU_RE = re.compile(r'[A-Za-z0-9][A-Za-z0-9._-]{0,63}\Z')
SCHEMA = '''
BEGIN IMMEDIATE;
CREATE TABLE IF NOT EXISTS item_state (
    sku TEXT PRIMARY KEY,
    last_sequence INTEGER NOT NULL CHECK(last_sequence >= 0),
    quantity INTEGER NOT NULL CHECK(quantity BETWEEN 0 AND 1000000000)
);
CREATE TABLE IF NOT EXISTS events (
    event_id TEXT PRIMARY KEY,
    sku TEXT NOT NULL,
    sequence INTEGER NOT NULL CHECK(sequence BETWEEN 1 AND 9223372036854775807),
    quantity INTEGER NOT NULL CHECK(quantity BETWEEN 0 AND 1000000000),
    payload_sha256 TEXT NOT NULL CHECK(length(payload_sha256) = 64),
    status TEXT NOT NULL CHECK(status IN ('pending', 'applied')),
    UNIQUE(sku, sequence),
    FOREIGN KEY(sku) REFERENCES item_state(sku)
);
CREATE INDEX IF NOT EXISTS idx_events_pending
    ON events(sku, status, sequence);
COMMIT;
'''

class Problem(Exception):
    def __init__(self, code, message, exit_code):
        super().__init__(message)
        self.code, self.message, self.exit_code = code, message, exit_code

def fail(code, message, exit_code):
    raise Problem(code, message, exit_code)

def emit(stream, value):
    json.dump(value, stream, ensure_ascii=False, sort_keys=True,
              separators=(',', ':'))
    stream.write('\n')

def unique_object(pairs):
    result = {}
    for key, value in pairs:
        if key in result:
            fail('duplicate_key', f'JSONキーが重複しています: {key}', 2)
        result[key] = value
    return result

def reject_constant(value):
    fail('invalid_number', f'JSONで使用できない数値です: {value}', 2)

def read_event():
    raw = sys.stdin.buffer.read(MAX_INPUT + 1)
    if len(raw) > MAX_INPUT:
        fail('input_too_large', '入力は4096バイト以内にしてください', 2)
    if not raw:
        fail('empty_input', '標準入力にJSONが必要です', 2)
    try:
        text = raw.decode('utf-8')
    except UnicodeDecodeError as exc:
        raise Problem('invalid_utf8', '入力はUTF-8にしてください', 2) from exc
    try:
        event = json.loads(text, object_pairs_hook=unique_object,
                           parse_constant=reject_constant)
    except (json.JSONDecodeError, RecursionError) as exc:
        raise Problem('invalid_json', '正しいJSONではありません', 2) from exc
    if not isinstance(event, dict) or set(event) != FIELDS:
        fail('invalid_fields', 'JSONの4項目が一致しません', 2)
    if not isinstance(event['event_id'], str) or not EVENT_ID_RE.fullmatch(event['event_id']):
        fail('invalid_event_id', 'event_idの形式が不正です', 2)
    if not isinstance(event['sku'], str) or not SKU_RE.fullmatch(event['sku']):
        fail('invalid_sku', 'skuの形式が不正です', 2)
    if type(event['sequence']) is not int or not 1 <= event['sequence'] <= MAX_SEQUENCE:
        fail('invalid_sequence', 'sequenceは1以上の整数にしてください', 2)
    if type(event['quantity']) is not int or not 0 <= event['quantity'] <= MAX_QUANTITY:
        fail('invalid_quantity', 'quantityは0以上1000000000以下の整数にしてください', 2)
    return event

def payload_hash(event):
    canonical = json.dumps(event, ensure_ascii=False, sort_keys=True,
                           separators=(',', ':')).encode('utf-8')
    return hashlib.sha256(canonical).hexdigest()

def next_expected(last):
    return last + 1 if last < MAX_SEQUENCE else None

def connect(db_path, create=False):
    if not create and not Path(db_path).is_file():
        fail('database_not_initialized', '先にinitを実行してください', 78)
    conn = sqlite3.connect(db_path, isolation_level=None, timeout=5.0)
    try:
        conn.row_factory = sqlite3.Row
        conn.execute('PRAGMA foreign_keys = ON')
        conn.execute('PRAGMA busy_timeout = 5000')
        conn.execute('PRAGMA synchronous = FULL')
    except BaseException:
        conn.close()
        raise
    return conn

def rollback(conn):
    if conn.in_transaction:
        conn.rollback()

def init_db(db_path):
    conn = connect(db_path, create=True)
    try:
        mode = conn.execute('PRAGMA journal_mode = WAL').fetchone()[0]
        if str(mode).lower() != 'wal':
            fail('wal_unavailable', 'WALを有効にできません', 78)
        conn.executescript(SCHEMA)
    except BaseException:
        rollback(conn)
        raise
    finally:
        conn.close()
    return {'ok': True, 'result': 'initialized', 'journal_mode': 'wal'}

def current(conn, sku):
    state = conn.execute(
        'SELECT last_sequence, quantity FROM item_state WHERE sku = ?', (sku,)
    ).fetchone()
    if state is None:
        fail('database_invariant', '商品状態が見つかりません', 70)
    pending = conn.execute(
        '''SELECT COUNT(*) FROM events
           WHERE sku = ? AND status = 'pending' ''', (sku,)
    ).fetchone()[0]
    return state, pending

def ingest(db_path, event):
    conn = connect(db_path)
    try:
        conn.execute('BEGIN IMMEDIATE')
        digest = payload_hash(event)
        old = conn.execute(
            '''SELECT sku, sequence, quantity, payload_sha256, status
               FROM events WHERE event_id = ?''',
            (event['event_id'],)
        ).fetchone()
        if old is not None:
            if (old['sku'] != event['sku'] or
                    old['sequence'] != event['sequence'] or
                    old['quantity'] != event['quantity'] or
                    old['payload_sha256'] != digest):
                fail('event_id_conflict',
                     '同じevent_idが異なる内容で登録済みです', 3)
            state, pending = current(conn, event['sku'])
            result = {
                'ok': True, 'result': 'duplicate',
                'event_id': event['event_id'], 'sku': event['sku'],
                'sequence': event['sequence'], 'event_status': old['status'],
                'applied_sequences': [],
                'last_applied_sequence': state['last_sequence'],
                'quantity': state['quantity'],
                'next_expected_sequence': next_expected(state['last_sequence']),
                'pending_count': pending,
            }
            conn.commit()
            return result

        conn.execute('INSERT OR IGNORE INTO item_state VALUES (?, 0, 0)',
                     (event['sku'],))
        state, _ = current(conn, event['sku'])
        occupied = conn.execute(
            'SELECT 1 FROM events WHERE sku = ? AND sequence = ?',
            (event['sku'], event['sequence'])
        ).fetchone()
        if occupied is not None:
            fail('sequence_conflict',
                 '同じ商品とsequenceに別のevent_idが登録済みです', 3)
        last = state['last_sequence']
        if event['sequence'] <= last:
            fail('stale_sequence', '適用済みより古いsequenceです', 3)
        if event['sequence'] > last + MAX_AHEAD:
            fail('sequence_too_far',
                 '現在値から1000を超える先のsequenceです', 3)
        conn.execute(
            '''INSERT INTO events
               (event_id, sku, sequence, quantity, payload_sha256, status)
               VALUES (?, ?, ?, ?, ?, 'pending')''',
            (event['event_id'], event['sku'], event['sequence'],
             event['quantity'], digest)
        )

        applied, quantity = [], state['quantity']
        while True:
            next_sequence = next_expected(last)
            if next_sequence is None:
                break
            row = conn.execute(
                '''SELECT event_id, quantity FROM events
                   WHERE sku = ? AND sequence = ? AND status = 'pending' ''',
                (event['sku'], next_sequence)
            ).fetchone()
            if row is None:
                break
            changed_event = conn.execute(
                '''UPDATE events SET status = 'applied'
                   WHERE event_id = ? AND status = 'pending' ''',
                (row['event_id'],)
            )
            changed_state = conn.execute(
                '''UPDATE item_state SET last_sequence = ?, quantity = ?
                   WHERE sku = ? AND last_sequence = ?''',
                (next_sequence, row['quantity'], event['sku'], last)
            )
            if changed_event.rowcount != 1 or changed_state.rowcount != 1:
                fail('database_invariant',
                     '連番適用中に状態が変わりました', 70)
            last, quantity = next_sequence, row['quantity']
            applied.append(next_sequence)

        status = conn.execute(
            'SELECT status FROM events WHERE event_id = ?',
            (event['event_id'],)
        ).fetchone()[0]
        _, pending = current(conn, event['sku'])
        result = {
            'ok': True,
            'result': 'applied' if status == 'applied' else 'buffered',
            'event_id': event['event_id'], 'sku': event['sku'],
            'sequence': event['sequence'], 'applied_sequences': applied,
            'last_applied_sequence': last, 'quantity': quantity,
            'next_expected_sequence': next_expected(last),
            'pending_count': pending,
        }
        conn.commit()
        return result
    except BaseException:
        rollback(conn)
        raise
    finally:
        conn.close()

def sqlite_failure(exc):
    name = str(getattr(exc, 'sqlite_errorname', ''))
    if name.startswith('SQLITE_BUSY'):
        return Problem('database_busy',
                       'SQLiteの書き込みロックを取得できませんでした', 75)
    if name.startswith('SQLITE_LOCKED'):
        return Problem('database_locked',
                       'SQLiteがSQLITE_LOCKEDを返しました', 70)
    return Problem('database_error', 'SQLiteの処理に失敗しました', 70)

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument('command', choices=('init', 'ingest'))
    parser.add_argument('db')
    args = parser.parse_args()
    try:
        result = (init_db(args.db) if args.command == 'init'
                  else ingest(args.db, read_event()))
        emit(sys.stdout, result)
        return 0
    except Problem as exc:
        emit(sys.stderr, {
            'ok': False,
            'error': {'code': exc.code, 'message': exc.message},
        })
        return exc.exit_code
    except sqlite3.Error as exc:
        converted = sqlite_failure(exc)
        emit(sys.stderr, {
            'ok': False,
            'error': {'code': converted.code,
                      'message': converted.message},
        })
        return converted.exit_code
    except OSError:
        emit(sys.stderr, {
            'ok': False,
            'error': {'code': 'file_error',
                      'message': 'ファイル操作に失敗しました'},
        })
        return 70
    except KeyboardInterrupt:
        emit(sys.stderr, {
            'ok': False,
            'error': {'code': 'interrupted', 'message': '中断しました'},
        })
        return 130

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

Python 3.11のjson公式資料にあるobject_pairs_hookを使い、同じJSONキーの重複を拒否しています。parse_constantも指定しているため、JSON仕様外のNaNやInfinityは受理しません。深すぎる入れ子によってjson.loads()がRecursionErrorを送出した場合も、invalid_jsonの1行JSONへ変換します。

イベント内容のSHA-256は、検証後の4項目をキー順に再構成して計算します。そのため、空白や項目順だけが異なる再送は同じ内容として扱われます。重複判定では、保存した各項目も照合します。

3、1、2の順で投入する

最初に専用のデータベースを初期化します。既存の別用途のSQLiteファイルは指定しません。

python3 sequence_buffer.py init inventory.db
{"journal_mode":"wal","ok":true,"result":"initialized"}

先に連番3を投入します。

printf '%s\n' '{"event_id":"evt-3","sku":"SKU-001","sequence":3,"quantity":30}' |
  python3 sequence_buffer.py ingest inventory.db
{"applied_sequences":[],"event_id":"evt-3","last_applied_sequence":0,"next_expected_sequence":1,"ok":true,"pending_count":1,"quantity":0,"result":"buffered","sequence":3,"sku":"SKU-001"}

連番1を投入すると、連番1だけが適用されます。連番2がないため、連番3は保留のままです。

printf '%s\n' '{"event_id":"evt-1","sku":"SKU-001","sequence":1,"quantity":10}' |
  python3 sequence_buffer.py ingest inventory.db
{"applied_sequences":[1],"event_id":"evt-1","last_applied_sequence":1,"next_expected_sequence":2,"ok":true,"pending_count":1,"quantity":10,"result":"applied","sequence":1,"sku":"SKU-001"}

最後に連番2を投入します。

printf '%s\n' '{"event_id":"evt-2","sku":"SKU-001","sequence":2,"quantity":20}' |
  python3 sequence_buffer.py ingest inventory.db
{"applied_sequences":[2,3],"event_id":"evt-2","last_applied_sequence":3,"next_expected_sequence":4,"ok":true,"pending_count":0,"quantity":30,"result":"applied","sequence":2,"sku":"SKU-001"}

applied_sequencesが[2,3]になり、保留していた連番3まで順番に適用されたことを確認できます。数量は差分加算ではないため、最終値は連番3の30です。

コミット後の再送では更新を繰り返さない

連番3と同じJSONをもう一度送ります。

printf '%s\n' '{"event_id":"evt-3","sku":"SKU-001","sequence":3,"quantity":30}' |
  python3 sequence_buffer.py ingest inventory.db
{"applied_sequences":[],"event_id":"evt-3","event_status":"applied","last_applied_sequence":3,"next_expected_sequence":4,"ok":true,"pending_count":0,"quantity":30,"result":"duplicate","sequence":3,"sku":"SKU-001"}

duplicate応答のevent_statusは、初回応答ではなく現在の保存状態です。最初はbufferedだったevt-3も、欠番解消後はappliedになっています。

同じイベントIDで数量だけを変更すると、IDの再利用として拒否します。

printf '%s\n' '{"event_id":"evt-3","sku":"SKU-001","sequence":3,"quantity":31}' |
  python3 sequence_buffer.py ingest inventory.db
printf 'exit=%s\n' "$?"
{"error":{"code":"event_id_conflict","message":"同じevent_idが異なる内容で登録済みです"},"ok":false}
exit=3

保存と連続適用を一つのトランザクションにする

SQLiteのトランザクション公式資料では、同時に存在できる書き込みトランザクションは一つであり、BEGIN IMMEDIATEは開始時点でSQLITE_BUSYになり得ると説明されています。

このCLIは、イベントの登録、保留イベントの状態変更、商品状態の更新を一つのBEGIN IMMEDIATEからCOMMITまでに行います。

停止した場所 データベース 再実行時
トランザクション開始前 変更なし 通常どおり受理する
イベント登録後、コミット前 登録をロールバックする 通常どおり受理する
複数連番の適用途中、コミット前 イベント状態と商品状態をまとめてロールバックする 同じ並びを再度適用する
コミット後、応答前 登録と適用が確定済み duplicateを返し、再適用しない

SQLITE_BUSYに対しては5000ミリ秒のロック待ちを設定し、待機後も取得できなければ終了コード75を返します。SQLITE_LOCKEDはbusy_timeoutで同じように待機できるエラーではないため、この実装では終了コード70として原因の確認を求めます。Python 3.11ではSQLite由来の例外にsqlite_errornameが付くため、エラー名で判定できます。詳細はPython 3.11のsqlite3公式資料で確認できます。

終了コードを配送側の判断に使う

終了コード 意味 配送側の扱い
0 applied、buffered、duplicate 受信成功として完了する
2 JSON、文字コード、項目、値、または引数の形式が不正 入力を修正するまで自動再送しない
3 ID競合、連番競合、古い連番、先読み範囲外 隔離して内容を確認する
70 データベース、ファイル、SQLITE_LOCKED、内部整合の失敗 原因を確認してから再実行する
75 SQLITE_BUSYによる書き込みロック競合 待機時間と上限回数を決めて再試行できる
78 未初期化、またはWALを利用できない 配置と初期化を確認する
130 キーボード操作による中断 自動成功とは扱わない

コマンド名や引数数の誤りは、処理開始前にargparseが使用方法を標準エラー出力へ表示し、終了コード2で終了します。この場合は1行JSONではありません。

WALでも商品ごとの並列書き込みにはならない

初期化時はSQLiteのWALモードを有効にし、戻り値がwalであることを確認します。各接続ではsynchronous=FULLも設定しています。設定の意味はSQLiteのPRAGMA公式資料で確認できます。

ただし、WALでも同時書き込みは一つです。SKU-001の処理中は、別商品の書き込みも同じデータベースの書き込みロックを待ちます。書き込み量や並行数が増えた場合は、トランザクション時間とロック待ちを計測したうえで構成を見直します。

運用前に確認する制約

  • 商品ごとの連番を発行する主体は一つにするか、複数発行者の間で重複しない割り当てを行います。
  • bufferedを失敗として無条件に再送せず、next_expected_sequenceとpending_countを監視します。
  • 先読み上限を超えたイベントは保存されません。欠番が埋まって現在値が進んだ後に再投入するか、隔離して調査します。
  • eventsには適用済み履歴も残るため、件数は増え続けます。削除すると過去のイベントIDを正確に重複判定できなくなるため、保存期間と別台帳を設計してから整理します。
  • この最小実装は受信時刻を保存しません。欠番の滞留時間を監視する場合は、時刻の取得元と保持方法を決めて列を追加します。
  • 署名や送信元認証は行いません。正当な発行元から届いたイベントであることは別の層で確認します。
  • initは既存スキーマを移行または検証する機能ではありません。専用のデータベースファイルを使用します。

到着順が入れ替わっても、商品状態は連番どおりに進みます。未来イベントの保存と業務状態への適用を分け、その両方を同じトランザクションで更新する構成です。