open question: FrameType.post_process seeds __flags__ with a bare 0, so a flagless HTTP/2 frame leaves it a plain int

[JarryShaw]

Filed as an open question, not an asserted defect. FrameType.post_process seeds its flag accumulator with a bare 0 and promotes it only as a side effect of |=, so an HTTP/2 frame with no flag bits set leaves __flags__ a plain int where both the schema and the data model declare it a Flags. That is the #616 shape exactly, and it reproduces end to end. What it is missing is #616's impact: no consumer anywhere in the library, its tests, its docs or its dump output observes the difference. Whether that makes it a defect or pre-emptive hardening is the open question.

Measured on 375e9d411, CPython 3.14.7, tree asserted against the worktree rather than the editable install. Both files below are byte-identical on current origin/main (da381f259).

Correction to where this lives

It is not in pcapkit/protocols/application/httpv2.py — that file has no post_process. It is in the schema:

pcapkit/protocols/schema/application/httpv2.py:129-147

    def post_process(self, packet: 'dict[str, Any]') -> 'Schema':
        ...
        flags = 0                                                    # 139
        for key, val in filter(lambda kv: kv[0].startswith('BIT_'),
                               self.Flags.__members__.items()):
            name = key.lower()
            if packet['flags'][name]:
                flags |= val                                         # 144

        self.__flags__ = flags                                       # 146
        return self

One accumulator, on FrameType (the base schema), inherited by all 11 frame schemas.

The declared type says Flags, and the sibling make path already agrees

• pcapkit/protocols/schema/application/httpv2.py:122 — __flags__: 'Flags' (under if TYPE_CHECKING:)
• pcapkit/protocols/data/application/httpv2.py:39 — __value__: 'FrameType.Flags'
• the enum is nested in the schema classes: FrameType.Flags at :126, per-frame subclasses at :165, :192, :276, :295, :328, :374. Nothing lives under pcapkit/const/http/ — that package has no flags module.

The decisive asymmetry: the construct side in the same package already seeds it correctly, six times — pcapkit/protocols/application/httpv2.py:

 949        flags = Schema_DataFrame.Flags(0)
 999        flags = Schema_HeadersFrame.Flags(0)
1097        flags = Schema_SettingsFrame.Flags(0)
1155        flags = Schema_PushPromiseFrame.Flags(0)
1189        flags = Schema_PingFrame.Flags(0)
1281        flags = Schema_ContinuationFrame.Flags(0)

Six correct Flags(0) seeds on the make side against one bare 0 on the parse side, which is what makes flags = 0 look like an oversight rather than a decision.

Measured — reproduces through the public parse path

Parsing real frame bytes via HTTP(io.BytesIO(raw), len(raw)).read() (note this library's length field counts the whole frame, header included — see the comment at tests/protocols/application/test_http_unit.py:561-570):

DATA flags=0x00 (none set)     __value__ type=int    repr=0
DATA flags=0x01 (END_STREAM)   __value__ type=Flags  repr=<Flags.END_STREAM: 1>
DATA flags=0x08 (PADDED)       __value__ type=Flags  repr=<Flags.PADDED: 8>

Promotion analysis. flags |= val is 0 | Flags.BIT_n; Flags overrides __ror__ via enum.Flag, so the reflected operation runs and returns a Flags. The 0 is never replaced wholesale — promotion is purely an operator side effect. When the loop body never runs, self.__flags__ = 0 stores a plain int.

A third path: five frame schemas define no BIT_ members at all (UnassignedFrame, PriorityFrame, RSTStreamFrame, GoawayFrame, WindowUpdateFrame), so for those the filter is empty and __flags__ is unconditionally plain int 0. Harmless, because all five pass flags=None into their data objects (httpv2.py:420, 568, 611, 816, 859) and never surface it.

The symptom against a consumer is #616's message verbatim:

END_STREAM in __value__  ->  TypeError: argument of type 'int' is not a container or iterable
control with Flags(0):  END_STREAM in DataFrame.Flags(0) -> False
and DataFrame.Flags(0) == 0 -> True   (so seeding Flags(0) is backward compatible)

Worth noting: the broken path is the common case, not the edge case. Unlike #616, where an all-zero TCP flags octet is unusual, an HTTP/2 flags byte of 0x00 is routine — every connection's opening SETTINGS frame, every non-final DATA frame, every non-ACK PING. So __value__ is a plain int for most frames in most captures.

Why it is an open question: every consumer is int-safe

Six frame types surface __flags__ into the data object, at httpv2.py:461, :515, :656, :718, :771, :895, each as '__value__': schema.__flags__. A repo-wide sweep for membership tests, iteration, .name access and Flags-class references found no consumer that would break:

Site	Use	Safe on a plain int?
httpv2.py:290	(int(flags) & (1 << bit)) >> bit	yes, explicit int()
httpv2.py:315	flags_int = int(flags)	yes, explicit int()
httpv2.py:319, 322, 323, 335	flags_int & int(Schema_*Frame.Flags.PADDED)	yes, int bitwise
httpv2.py:396	data.flags.__value__ if data.flags is not None else 0	yes, pass-through
httpv2.py:461, 515, 656, 718, 771, 895	'__value__': schema.__flags__	yes, just stores it
httpv2.py:244	flags: 'Flags' = 0, # type: ignore[assignment]	the public make default is already a bare 0, with a silencing comment

Nor is it visible in a dump — dictdumper output is identical on both paths ("__value__": 0 / |-- __value__ -> 0). The only observable difference is repr(). And Flags = Schema_FrameType.Flags at httpv2.py:83 is inside if TYPE_CHECKING:, so HTTP.Flags raises AttributeError at runtime — the enum is not public runtime API.

The existing test does not pin the type either: tests/protocols/application/test_http_unit.py:1080 is self.assertEqual(plain.__flags__, 0), which passes for both plain int 0 and Flags(0), since IntFlag compares equal to int.

These are stdlib enum, not aenum — and it does not change the answer

FrameType.Flags.__mro__ = (<flag 'Flags'>, <flag 'IntFlag'>, <class 'int'>, <enum 'ReprEnum'>, <flag 'Flag'>, <enum 'Enum'>, <class 'object'>)
module of the base enum  = enum
aenum.IntFlag in mro?    = False
TCP Flags.__mro__       = (<aenum 'Flags'>, <aenum 'IntFlag'>, ...)

pcapkit/protocols/schema/application/httpv2.py:6 is import enum and :126 is class Flags(enum.IntFlag):, whereas #616's TCP flags are aenum.IntFlag (pcapkit/const/tcp/flags.py:15). Recording this explicitly because mis-stating the enum library is how #623's root cause went wrong once already. It does not change the diagnosis: the TypeError comes from the left operand being a plain int (which has no __contains__), which is library-independent; |= promotes identically in both; and stdlib enum.IntFlag accepts Flags(0) for an empty flag set, so the one-token fix is available either way.

The boundary of what was established

Established: the seed is a plain int; it promotes only when a bit is set; the no-bits path is reachable through the public parse path and is the common case; both the schema and the data model declare the type as Flags; the make path already uses the correct idiom six times; the fix is backward-compatible for every existing consumer.

Not established: any consumer — in pcapkit, its tests, its docs, or its dump output — that observes the difference. None was found, after searching for membership tests, iteration, .name access, Flags-class references and serialization differences.

The decision this needs: whether a declared-type violation on a reachable path counts as a defect here in its own right. If yes, the fix is one token — flags = self.Flags(0) at pcapkit/protocols/schema/application/httpv2.py:139 — plus a test asserting isinstance(plain.__flags__, DataFrame.Flags) to replace the type-blind assertEqual(..., 0) at test_http_unit.py:1080. If no, this is a latent-hazard note and the honest framing is "pre-emptive hardening against the #616 class", not "bug fix".

Notes

• Surfaced by the cross-reviewer on PR fix(tcp): seed TCP.read's flag accumulator with Enum_Flags(0), not a no-op cast (#616) #634 (for TCP.read seeds _flags with a no-op cast, so a flagless segment leaves it a plain int #616) and never investigated; this issue is that investigation.
• The same investigation turned up a confirmed behavioural defect a few lines away in the sibling file — _make_http_data never reads frame.flags, so END_STREAM is silently dropped on a parse → reconstruct round trip. That is _make_http_data never reads frame.flags, so END_STREAM is silently dropped on a parse-reconstruct round trip #652, and it is independent of this one: fixing either leaves the other.
• Same shape as TCP.read seeds _flags with a no-op cast, so a flagless segment leaves it a plain int #616 (TCP.read seeding cast('Enum_Flags', 0), a runtime no-op) and fix(tcp): resolve the connection flags before building the options (#587) #597 (which fixed the same pattern on TCP's make path). The difference from both is that TCP.read seeds _flags with a no-op cast, so a flagless segment leaves it a plain int #616's _flags is read by the MPTCP dispatchers with Enum_Flags.SYN in self._flags, which is what gave it teeth. There is no equivalent read here.

[JarryShaw]

Investigated, and the answer is yes, fix it — because the premise that no consumer observes it turns out to be false. Fixed in #669.

The decisive measurement is the one this issue flagged as worth making: whether the #634 rendering change happens here too. It does. Real parsed frames, through this library's own make_dumper, on 0c7f2b7c9:

BEFORE
  flags=0x00 flagless:        type(__value__) = int
    json  "__value__": 0
    tree  |-- __value__ -> 0
  flags=0x01 END_STREAM set:  type(__value__) = Flags
    json  "__value__": "Flags::END_STREAM [1]"
    tree  |-- __value__ -> Flags::END_STREAM [1]

AFTER
  flags=0x00 flagless:        type(__value__) = Flags
    json  "__value__": "Flags::None [0]"
    tree  |-- __value__ -> Flags::None [0]
  flags=0x01 END_STREAM set:  unchanged

So this issue's "Not established" section — "any consumer ... that observes the difference. None was found" — is refuted, and by the dump output specifically. The observable defect is sharper than "the type is wrong internally": __value__ was a JSON number for a flagless frame and a JSON string for every other frame in the same capture. Since a 0x00 flags octet is the common case, most frames rendered as a number and the rest as a string, in one file. The fix makes it uniformly a string. That is exactly the argument #634 made for TCP's connection, and #634 shipped as fix + breaking.

The reason the earlier sweep missed it is that the comparison was between the two pre-fix paths, where the flagless frame does dump 0 and nothing looks inconsistent until you ask what the fixed flagless frame dumps.

Two corrections to this issue's proposed fix, both measured:

1. On Python 3.12 and later, the one-token fix would have crashed six of the twelve frame schemas. flags = self.Flags(0) is not safe, because FrameType.Flags declares no members and — from the 3.12 enum rewrite — a memberless enum.Flag subclass refuses instantiation (measured on 3.14.7):

FrameType         BIT_ members=0  RAISED TypeError: <flag 'Flags'> has no members
UnassignedFrame   BIT_ members=0  RAISED TypeError: <flag 'Flags'> has no members
PriorityFrame     BIT_ members=0  RAISED TypeError: <flag 'Flags'> has no members
RSTStreamFrame    BIT_ members=0  RAISED TypeError: <flag 'Flags'> has no members
GoawayFrame       BIT_ members=0  RAISED TypeError: <flag 'Flags'> has no members
WindowUpdateFrame BIT_ members=0  RAISED TypeError: <flag 'Flags'> has no members
DataFrame         BIT_ members=2  OK  <Flags: 0>
HeadersFrame      BIT_ members=4  OK  <Flags: 0>
SettingsFrame     BIT_ members=1  OK  <Flags: 0>
PushPromiseFrame  BIT_ members=2  OK  <Flags: 0>
PingFrame         BIT_ members=1  OK  <Flags: 0>
ContinuationFrame BIT_ members=1  OK  <Flags: 0>

That is the same five frame schemas this issue already identified as declaring no BIT_ members — the issue is right that they are harmless, but instantiating their inherited enum is not harmless. #669 guards the seed: self.Flags(0) if self.Flags.__members__ else 0, and pins both the guard and the reason for it in a test so it cannot be "simplified" back into a crash.

The version dependence is worth stating precisely, because it also shapes the test. The behaviour flipped in the enum rewrite:

version 3.14.7  members: 0  Flags(0) -> TypeError: <flag 'Flags'> has no members; …
version 3.7.16  members: 0  Flags(0) -> OK <Flags.0: 0>

CI runs the unit tier on 3.10 through 3.15, so #669's test asserts the memberless-ness unconditionally — that being the predicate the guard keys on — and gates only the TypeError behind sys.version_info >= (3, 12). The guard itself is correct on every supported interpreter: necessary from 3.12, harmless before.

2. The enum library note in this issue is correct, and I verified it rather than taking it on trust. These are stdlib enum.IntFlag:

issubclass(DataFrame.Flags, enum.IntFlag)  = True
issubclass(DataFrame.Flags, aenum.IntFlag) = False
TCP Flags (contrast) = (<aenum 'Flags'>, <aenum 'IntFlag'>, ...)  aenum: True

pcapkit/const/tcp/flags.py was read, not edited — #661 owns const changes.

Everything else this issue established held up: the seed is a plain int; |= promotes only as a side effect; the flagless path is reachable through the public parse path and is the common case; END_STREAM in __value__ raises TypeError: argument of type 'int' is not a container or iterable; and Flags(0) == 0 is True, so every int-safe consumer the table enumerates is unaffected.

One thing found on the way, unrelated to flags and not fixed in #669: three payload length callbacks in the same schema file are mis-parenthesised, so an unpadded DATA, HEADERS or PUSH_PROMISE frame parses with its whole payload dropped. Filed as #668.