第193回 巨大な欠番を一度に要求しない:Pythonで作る上限付き再送リクエスト

第192回では、SQLiteで確認した欠番を、連番ごとに展開せず範囲へまとめました。今回は、その欠番範囲の先頭から指定件数だけを選び、一つの再送リクエストJSONを作ります。

作成するCLIは、通信、データベース更新、イベントの再適用を行いません。再送元と合意した上限に収まる要求を標準出力へ生成するところまでを担当します。残りを古いレポートから続けて要求せず、再送結果を反映してから欠番レポートを取り直します。

本稿のJSONはローカルな交換形式です。PythonやSQLiteの標準プロトコルではありません。既存のAPIがある場合は、範囲の意味、認証方法、最大件数をその契約へ合わせてください。

範囲を展開せず、先頭から上限まで選ぶ

適用済み連番が10、確認済み上限が30で、欠番が11~20と25~29だったとします。上限を12件にすると、11~20の10件と25~26の2件を要求します。27~29は今回の要求へ含めません。

入力状態 処理 結果
11~999999が欠番 範囲の長さを引き算で求める 各連番をメモリへ展開しない
上限が1000件 範囲の先頭1000件だけを選ぶ 11~1010という一つの閉区間になる
複数の欠番範囲がある 連番の小さい範囲から選ぶ 最後に採用する範囲だけ途中で分割され得る
欠番がない 要求を作らない no_requestを返す
同じレポートから同じ範囲を選ぶ 時刻を含めず、キー順と区切り方を固定する 同じリクエストIDになる

event_countは範囲数ではなく、範囲に含まれる連番の個数です。startとendは両端を含みます。

入力と終了コードの契約

項目 仕様
動作環境 Python 3.11以上、標準ライブラリのみ
入力 UTF-8のJSONファイル。上限は1,048,576バイト
連番 0~2147483647。missing_rangesの値は1以上
observed_through レポート作成時に存在を確認した最大連番。欠番範囲の終端はこの値未満
欠番範囲 昇順、重複なし、隣接なし。欠番がある場合、先頭はapplied_through + 1
--max-events 必須。1~2147483647の範囲で、再送元が受理できる上限を指定する
標準出力 成功時も入力エラー時もUTF-8の1行JSON。ただし--helpは説明文
終了コード0 request_readyまたはno_request
終了コード2 引数、ファイル、JSON、入力値のエラー

入力の形だけでは、欠番が再送元へ残っているか、レポートがデータベースの最新状態かまでは証明できません。ここでは、範囲同士の矛盾と実装上の上限を検査します。ファイルサイズ内であっても、実行環境の再帰上限を超える深いJSONや、Pythonが整数へ変換できない桁数の数値は入力エラーとして扱います。

上限付きリクエストを作るCLI

次の内容をmake_replay_request.pyとして保存します。

#!/usr/bin/env python3
import argparse
import hashlib
import json
import sys
import unicodedata
from pathlib import Path

MAX_INPUT_BYTES = 1024 * 1024
MAX_RANGES = 10_000
MAX_SEQUENCE = 2_147_483_647


class InputError(Exception):
    pass


class JsonArgumentParser(argparse.ArgumentParser):
    def error(self, message):
        raise InputError(f'引数が不正です: {message}')


def canonical(value):
    return json.dumps(
        value,
        ensure_ascii=False,
        sort_keys=True,
        separators=(',', ':'),
        allow_nan=False,
    )


def digest(value):
    data = canonical(value).encode('utf-8')
    return 'sha256:' + hashlib.sha256(data).hexdigest()


def emit(value):
    text = canonical(value)
    data = text.encode('utf-8', errors='backslashreplace')
    sys.stdout.buffer.write(data + b'\n')


def unique_object(pairs):
    result = {}
    for key, value in pairs:
        if key in result:
            raise InputError(f'JSONに重複キーがあります: {key}')
        result[key] = value
    return result


def reject_constant(value):
    raise InputError(f'JSONで許可しない値です: {value}')


def load_json(path):
    try:
        with path.open('rb') as input_file:
            raw = input_file.read(MAX_INPUT_BYTES + 1)
    except OSError as exc:
        detail = exc.strerror or exc.__class__.__name__
        raise InputError(f'入力ファイルを読めません: {detail}') from exc

    if len(raw) > MAX_INPUT_BYTES:
        raise InputError(f'入力ファイルは{MAX_INPUT_BYTES}バイト以下にしてください')

    try:
        text = raw.decode('utf-8')
    except UnicodeDecodeError as exc:
        raise InputError('入力ファイルはUTF-8ではありません') from exc

    try:
        return json.loads(
            text,
            object_pairs_hook=unique_object,
            parse_constant=reject_constant,
        )
    except InputError:
        raise
    except json.JSONDecodeError as exc:
        raise InputError(
            f'JSONが不正です({exc.lineno}行{exc.colno}列)'
        ) from exc
    except (RecursionError, ValueError) as exc:
        raise InputError('JSONが実装上の解析上限を超えています') from exc


def strict_object(value, expected, name):
    if type(value) is not dict:
        raise InputError(f'{name}はオブジェクトにしてください')

    actual = set(value)
    if actual != expected:
        missing = ','.join(sorted(expected - actual)) or '-'
        extra = ','.join(sorted(actual - expected)) or '-'
        raise InputError(
            f'{name}のキーが不正です(不足={missing}、未定義={extra})'
        )
    return value


def bounded_int(name, value, minimum, maximum):
    if type(value) is not int or not minimum <= value <= maximum:
        raise InputError(
            f'{name}は{minimum}以上{maximum}以下の整数にしてください'
        )
    return value


def validate_report(value):
    report = strict_object(
        value,
        {
            'schema_version',
            'stream_id',
            'applied_through',
            'observed_through',
            'missing_ranges',
        },
        '最上位',
    )

    if type(report['schema_version']) is not int or report['schema_version'] != 1:
        raise InputError('schema_versionは整数の1にしてください')

    stream_id = report['stream_id']
    if type(stream_id) is not str or not 1 <= len(stream_id) <= 128:
        raise InputError('stream_idは1~128文字の文字列にしてください')
    if stream_id != stream_id.strip():
        raise InputError('stream_idの前後に空白を入れないでください')
    if any(
        unicodedata.category(char) in {'Cc', 'Cs'}
        for char in stream_id
    ):
        raise InputError(
            'stream_idに制御文字やサロゲートを入れないでください'
        )

    applied = bounded_int(
        'applied_through', report['applied_through'], 0, MAX_SEQUENCE
    )
    observed = bounded_int(
        'observed_through', report['observed_through'], 0, MAX_SEQUENCE
    )
    if observed < applied:
        raise InputError('observed_throughはapplied_through以上にしてください')

    raw_ranges = report['missing_ranges']
    if type(raw_ranges) is not list:
        raise InputError('missing_rangesは配列にしてください')
    if len(raw_ranges) > MAX_RANGES:
        raise InputError(f'missing_rangesは{MAX_RANGES}件以下にしてください')

    ranges = []
    previous_end = None

    for index, raw_range in enumerate(raw_ranges):
        item = strict_object(
            raw_range,
            {'start', 'end'},
            f'missing_ranges[{index}]',
        )
        start = bounded_int(
            f'missing_ranges[{index}].start', item['start'], 1, MAX_SEQUENCE
        )
        end = bounded_int(
            f'missing_ranges[{index}].end', item['end'], 1, MAX_SEQUENCE
        )

        if start > end:
            raise InputError(
                f'missing_ranges[{index}]はstartをend以下にしてください'
            )
        if start <= applied:
            raise InputError(
                f'missing_ranges[{index}].startは'
                'applied_throughより大きくしてください'
            )
        if end >= observed:
            raise InputError(
                f'missing_ranges[{index}].endは'
                'observed_through未満にしてください'
            )
        if previous_end is not None and start <= previous_end:
            raise InputError(
                f'missing_ranges[{index}]は前の範囲と重複または逆順です'
            )
        if previous_end is not None and start == previous_end + 1:
            raise InputError(
                f'missing_ranges[{index}]は前の範囲と結合してください'
            )

        ranges.append({'start': start, 'end': end})
        previous_end = end

    if not ranges:
        if observed != applied:
            raise InputError(
                'missing_rangesが空ならobserved_throughを'
                'applied_throughと同じにしてください'
            )
    elif ranges[0]['start'] != applied + 1:
        raise InputError(
            '最初の欠番範囲はapplied_through + 1から始めてください'
        )

    return {
        'schema_version': 1,
        'stream_id': stream_id,
        'applied_through': applied,
        'observed_through': observed,
        'missing_ranges': ranges,
    }


def max_events_value(text):
    try:
        value = int(text, 10)
    except ValueError as exc:
        raise argparse.ArgumentTypeError('整数を指定してください') from exc
    if not 1 <= value <= MAX_SEQUENCE:
        raise argparse.ArgumentTypeError(
            f'1以上{MAX_SEQUENCE}以下を指定してください'
        )
    return value


def select_ranges(ranges, limit):
    selected = []
    selected_count = 0

    for item in ranges:
        if selected_count == limit:
            break
        available = item['end'] - item['start'] + 1
        take = min(available, limit - selected_count)
        selected.append({
            'start': item['start'],
            'end': item['start'] + take - 1,
        })
        selected_count += take

    return selected, selected_count


def make_output(report, limit):
    report_hash = digest(report)

    if not report['missing_ranges']:
        return {
            'status': 'no_request',
            'stream_id': report['stream_id'],
            'applied_through': report['applied_through'],
            'observed_through': report['observed_through'],
            'report_sha256': report_hash,
            'total_missing_event_count': 0,
        }

    total_count = sum(
        item['end'] - item['start'] + 1
        for item in report['missing_ranges']
    )
    selected, selected_count = select_ranges(
        report['missing_ranges'], limit
    )

    request_core = {
        'schema_version': 1,
        'kind': 'sequence_range_replay_request',
        'stream_id': report['stream_id'],
        'range_end_inclusive': True,
        'based_on': {
            'applied_through': report['applied_through'],
            'observed_through': report['observed_through'],
            'report_sha256': report_hash,
        },
        'ranges': selected,
        'event_count': selected_count,
    }
    request = dict(request_core)
    request['request_id'] = digest(request_core)

    return {
        'status': 'request_ready',
        'request': request,
        'total_missing_event_count': total_count,
        'remaining_event_count': total_count - selected_count,
        'truncated': selected_count < total_count,
    }


def build_parser():
    parser = JsonArgumentParser(
        description='欠番範囲から上限付き再送リクエストを作る'
    )
    parser.add_argument('input', type=Path, help='欠番レポートJSON')
    parser.add_argument(
        '--max-events',
        required=True,
        type=max_events_value,
        help='一つの要求へ含める連番数の上限',
    )
    return parser


def main():
    try:
        args = build_parser().parse_args()
        report = validate_report(load_json(args.input))
        output = make_output(report, args.max_events)
    except InputError as exc:
        emit({'status': 'error', 'error': str(exc)})
        return 2

    emit(output)
    return 0


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

load_jsonでは、構文エラーに加えてRecursionErrorとValueErrorもInputErrorへ変換します。これにより、深すぎる入れ子やPython 3.11の整数文字列変換上限を超える数値でも、トレースバックを表示せず1行JSONと終了コード2を返します。

選択処理が反復するのは欠番範囲ごとです。11~999999を扱う場合でも、11から順に整数を生成するループはありません。

12件に制限して実行する

次の内容をgap_ranges.jsonとして保存します。observed_throughの30は、連番30が存在すると確認したことを表します。そのため、最後の欠番は29までです。

{
  "schema_version": 1,
  "stream_id": "inventory:SKU-001",
  "applied_through": 10,
  "observed_through": 30,
  "missing_ranges": [
    {"start": 11, "end": 20},
    {"start": 25, "end": 29}
  ]
}

CLIを実行します。終了コードが0の場合だけ、request.jsonを次の処理へ渡します。

python3 make_replay_request.py gap_ranges.json --max-events 12 > request.json
rc=$?
echo exit=$rc
if [ "$rc" -ne 0 ]; then
    cat request.json
fi

正常時、端末には次の終了コードが表示されます。

exit=0

終了コードが0であることを確認したら、生成された範囲、件数、残件数、リクエストIDを検証します。

python3 - <<'PY'
import hashlib
import json
from pathlib import Path

data = json.loads(Path('request.json').read_text(encoding='utf-8'))
assert data['status'] == 'request_ready'
assert data['request']['ranges'] == [
    {'start': 11, 'end': 20},
    {'start': 25, 'end': 26},
]
assert data['request']['event_count'] == 12
assert data['total_missing_event_count'] == 15
assert data['remaining_event_count'] == 3
assert data['truncated'] is True

request = data['request']
core = {
    key: value
    for key, value in request.items()
    if key != 'request_id'
}
encoded = json.dumps(
    core,
    ensure_ascii=False,
    sort_keys=True,
    separators=(',', ':'),
    allow_nan=False,
).encode('utf-8')
expected_id = 'sha256:' + hashlib.sha256(encoded).hexdigest()
assert request['request_id'] == expected_id
print('検証OK')
PY

出力は次の1行です。

検証OK

request_idは、リクエスト本体のキー順と区切り方を固定してSHA-256を計算した値です。同じ要求内容を識別できますが、電子署名や認証情報ではありません。内容を書き換えられる主体は、新しいハッシュも計算できます。

report_sha256も元ファイルのバイト列に対するハッシュではありません。検証後のレポートを固定した形式へ変換して計算します。空白やキー順だけが異なる入力は同じ値になります。

解析上限を超えるJSONも入力エラーにする

1MiB未満でも、極端に深くネストしたJSONはjson.loadsでRecursionErrorになる場合があります。また、Python 3.11の既定設定では、非常に桁数の多い整数を変換するとValueErrorになります。次の確認では、そのどちらも終了コード2へ変換されることを確かめます。

python3 - <<'PY'
from pathlib import Path

Path('too_deep.json').write_text(
    '[' * 2000 + '0' + ']' * 2000,
    encoding='utf-8',
)
Path('too_many_digits.json').write_text(
    '{"schema_version":' + '1' * 5000 + '}',
    encoding='utf-8',
)
PY

python3 make_replay_request.py too_deep.json --max-events 12
echo exit=$?
python3 make_replay_request.py too_many_digits.json --max-events 12
echo exit=$?

Pythonの既定の解析上限に達した場合、各実行は次の1行JSONと終了コード2を返します。

{"error":"JSONが実装上の解析上限を超えています","status":"error"}
exit=2
{"error":"JSONが実装上の解析上限を超えています","status":"error"}
exit=2

矛盾した範囲は要求へ変換しない

次のbad_ranges.jsonでは、二つ目の範囲が連番20で重複しています。

{
  "schema_version": 1,
  "stream_id": "inventory:SKU-001",
  "applied_through": 10,
  "observed_through": 30,
  "missing_ranges": [
    {"start": 11, "end": 20},
    {"start": 20, "end": 29}
  ]
}
python3 make_replay_request.py bad_ranges.json --max-events 12
echo exit=$?

標準出力と終了コードは次のとおりです。要求は生成されません。

{"error":"missing_ranges[1]は前の範囲と重複または逆順です","status":"error"}
exit=2

missing_rangesが空の場合は、observed_throughとapplied_throughが同じであることを確認し、終了コード0でno_requestを返します。適用済み連番より先のイベントが存在するのに欠番がない状態は、並べ替えバッファに適用可能なイベントが残っている可能性があるため、入力エラーとします。

再送後は欠番レポートを取り直す

  1. 同じ時点の適用済み連番、確認済み上限、欠番範囲を得る。
  2. 再送元が受理できる件数を--max-eventsへ指定し、リクエストJSONを作る。
  3. 終了コードと内容を確認し、既存の認証済み経路がある場合に限って要求を渡す。
  4. 返されたイベントを通常の受信処理へ入力する。
  5. 適用結果を反映した後、欠番レポートを取り直して次の要求を作る。

remaining_event_countは入力レポート時点の計算値です。再送中に別経路からイベントが届けば、現在の欠番とは一致しなくなります。そのため、残件数だけを頼りに次の要求位置を進めません。

同じrequest_idが繰り返し生成された場合、同じ要求内容が生成されたことは確認できます。ただし、古いレポートを再利用している可能性は残ります。配送失敗、再送元での保存期限切れ、権限不足、受信処理の停止も、このCLIだけでは判定できません。

この実装で扱わない範囲

対象外 別途必要な対策
要求者の認証と権限 再送元との認証・認可契約
通信失敗やタイムアウト 配送処理側の再試行方針と記録
リクエストIDの二重処理防止 受信側での内容照合と永続的な重複記録
イベントが保存されている保証 再送元の保存期間と欠損時の業務判断
意図的に飛ばす連番 連続整数を前提にしない別の識別方式

検証環境では小さい上限から始め、選ばれた閉区間と再送元の件数解釈が一致することを確認します。再送後に欠番レポートを取り直せば、大きな欠番を個別番号へ展開せずに処理できます。