The Counter That Counted a Call the Preflight Never Reached

那个统计了“预检未通过”调用的计数器

Summer Bug Smash: Clear the Lineup 🐛🛹 This is a submission for DEV’s Summer Bug Smash: Clear the Lineup, powered by Sentry. 夏季 Bug 扫除：清理队列 🐛🛹 这是为 DEV 的“夏季 Bug 扫除：清理队列”（由 Sentry 提供支持）活动提交的作品。

Project Overview

项目概述

I was working on a small Python component that performs a preflight check and then, if the check succeeds, invokes one synchronous operation callback. A counter records whether that callback invocation returned normally. The counter is used for diagnostics, so it must follow the control flow rather than the expected happy path. 我当时正在开发一个小型 Python 组件，它会执行一次预检（preflight check），如果检查成功，则调用一个同步操作回调。有一个计数器用于记录该回调是否正常返回。由于该计数器用于诊断，因此它必须反映实际的控制流，而不是预期的“理想路径”。

Bug Fix or Performance Improvement

Bug 修复或性能改进

When a handled failure occurred, the old implementation still returned one: return 1. That value was hard-coded because the successful path was expected to invoke exactly one operation. If the preflight check failed, however, the operation was never entered and the function still returned one. An offline reproduction produced: operation_entries=0, old_count=1. The failure was handled, but the counter contradicted the actual control flow. 当发生已处理的故障时，旧的实现仍然返回 1：return 1。这个值是硬编码的，因为在成功路径下预期只会调用一次操作。然而，如果预检失败，操作根本不会被执行，但函数依然返回了 1。离线复现的结果显示：operation_entries=0，old_count=1。虽然故障被处理了，但计数器与实际的控制流相矛盾。

Code

代码

Reduced to the relevant lines, the old behavior was: 简化到相关代码行，旧的行为如下：

# Simplified pre-fix behavior
def buggy_completed_calls(*, preflight, operation):
    try:
        preflight()
        operation()
    except Exception:
        pass
    return 1

Here is the complete fixed function from the standalone reproducer: 以下是来自独立复现程序的完整修复函数：

from collections.abc import Callable
Callback = Callable[[], None]

def completed_calls(*, preflight: Callback, operation: Callback) -> int:
    """Return one only when the cooperative operation returned normally."""
    try:
        preflight()
        operation()
    except Exception:
        return 0
    return 1

The essential regression assertion is shown below. Both callbacks are local, so the test performs no network request: 必要的回归断言如下所示。由于两个回调都是局部的，因此测试不会执行任何网络请求：

# Abbreviated test excerpt
def test_preflight_failure_does_not_count_an_unentered_operation():
    operation_entries = 0
    def refuse_preflight():
        raise RuntimeError("controlled preflight refusal")
    def operation():
        nonlocal operation_entries
        operation_entries += 1
    
    result = completed_calls(
        preflight=refuse_preflight,
        operation=operation,
    )
    assert operation_entries == 0
    assert result == 0

My Improvements

我的改进

The design change is simple: a handled failure returns zero directly, while the only path to one comes after the operation callback invocation returns normally. Expected control flow no longer substitutes for observed control flow. 设计上的改动很简单：已处理的故障直接返回 0，而只有当操作回调正常返回时，才会返回 1。预期的控制流不再替代实际观察到的控制流。

I verified the change with: an exact before/after replay of the preflight failure; tests under normal Python execution and python -O; in-memory compilation checks; no network or external service access. 我通过以下方式验证了该改动：对预检失败进行了精确的修复前后重现；在常规 Python 执行和 python -O 模式下进行了测试；进行了内存编译检查；且不涉及任何网络或外部服务访问。

The exact invariant fixed here is: PREFLIGHT_RAISES_EXCEPTION_BEFORE_OPERATION_CALL => completed_calls == 0. Here, EXCEPTION means Python’s Exception, not BaseException. 此处修复的精确不变式是：PREFLIGHT_RAISES_EXCEPTION_BEFORE_OPERATION_CALL => completed_calls == 0。这里的 EXCEPTION 指的是 Python 的 Exception，而非 BaseException。

There is another important boundary I do not want to hide: the counter measures normal callback-invocation returns, not deferred work or remote side effects. If a called operation causes an external effect and then raises while waiting for a result, this integer alone cannot describe what happened remotely. The declared profile is ordinary cooperative synchronous application code in one process. This helper is not a sandbox for hostile callbacks. Within its stated scope, the bug is closed: a preflight failure can no longer produce a false-positive completed-call count. 还有一个重要的边界我不希望隐瞒：该计数器衡量的是回调调用的正常返回，而不是延迟任务或远程副作用。如果一个被调用的操作产生了外部影响，随后在等待结果时抛出异常，那么仅凭这个整数无法描述远程发生了什么。该组件的定位是单进程中普通的协作式同步应用代码。此辅助函数并非针对恶意回调的沙箱。在其声明的范围内，该 Bug 已被修复：预检失败不再会产生误报的“已完成调用”计数。