@@ -21,12 +21,12 @@ The member list takes either of these forms:
2121 :class: `~pcapkit.protocols.internet.esp.ESP ` are not in it, since they belong to
2222 the separate abstract :class: `~pcapkit.protocols.internet.ipsec.IPsec `, whose
2323 :meth: `~pcapkit.protocols.internet.ipsec.IPsec.id ` is ``('AH', 'ESP') ``.
24+ :meth: `HTTP.id() <pcapkit.protocols.application.http.HTTP.id> ` is
25+ ``('HTTP/1', 'HTTP/2') ``.
2426* **The base's own name, then the members. **
2527 :meth: `VLAN.id() <pcapkit.protocols.link.vlan.VLAN.id> ` is
26- ``('VLAN', 'C_Tag', 'S_Tag') ``,
27- :meth: `L2TP.id() <pcapkit.protocols.link.l2tp.L2TP.id> ` is ``('L2TP', 'L2TPv2') ``
28- and :meth: `HTTP.id() <pcapkit.protocols.application.http.HTTP.id> ` is
29- ``('HTTP', 'HTTPv1', 'HTTPv2') ``.
28+ ``('VLAN', 'C_Tag', 'S_Tag') `` and
29+ :meth: `L2TP.id() <pcapkit.protocols.link.l2tp.L2TP.id> ` is ``('L2TP', 'L2TPv2') ``.
3030
3131:meth: `ARP.id() <pcapkit.protocols.link.arp.ARP.id> ` is ``('ARP',) `` alone; see
3232:ref: `protocol-family-shapes `.
@@ -48,7 +48,29 @@ HTTP/2 share :class:`~pcapkit.protocols.application.http.HTTP`, IPv4 and IPv6 sh
4848
4949:class: `~pcapkit.protocols.internet.ip.IP ` and
5050:class: `~pcapkit.protocols.internet.ipsec.IPsec ` define no ``read() ``. The HTTP class
51- does, and a parsed HTTP/1.1 or HTTP/2 layer is the HTTP class itself.
51+ does, but yields no instance of itself (:ref: `below <protocol-family-dispatch >`).
52+
53+ .. _protocol-family-dispatch :
54+
55+ Dispatching Bases
56+ ~~~~~~~~~~~~~~~~~
57+
58+ **A versioned family's base dispatches on both paths ** (:issue: `2524 `). Parsing
59+ octets through it, constructing it from fields and its ``from_data `` give the member
60+ the octets, fields or data model describe, never an instance of the base. In
61+ :class: `~pcapkit.protocols.application.http.HTTP `,
62+ :meth: `~pcapkit.protocols.application.http.HTTP._dispatch_version ` picks the member
63+ from the octets, for a payload a transport port binds to HTTP as well, and
64+ :meth: `~pcapkit.protocols.application.http.HTTP._dispatch_fields ` from the fields.
65+ The other versioned families are tracked on :issue: `2574 `.
66+
67+ **Octets neither version takes **, a frameless HTTP/2 connection preface among them,
68+ are :class: `~pcapkit.protocols.misc.raw.Raw ` with no ``error `` on the transport path,
69+ and a direct ``HTTP(...) `` on them raises
70+ :exc: `~pcapkit.utilities.exceptions.ProtocolError ` (:issue: `2524 `). Octets the
71+ dispatcher gives :class: `~pcapkit.protocols.application.httpv2.HTTPv2 ` that its parser
72+ then refuses, such as a preface and three octets, are
73+ :class: `~pcapkit.protocols.misc.raw.Raw ` with the parser's ``error ``.
5274
5375.. _protocol-family-shapes :
5476
@@ -70,15 +92,14 @@ Member Shapes
7092 :class: `IGMPv3 <pcapkit.protocols.internet.igmpv3.IGMPv3> ` ``('IGMPv3',) `` --
7193 :class: `IGMPv1 <pcapkit.protocols.internet.igmpv1.IGMPv1> ` narrows the same way,
7294 but to the RFC canonical name rather than a versioned one
73- (:ref: `protocol-family-canonical-names `)
95+ (:ref: `protocol-family-canonical-names `);
96+ :class: `HTTPv1 <pcapkit.protocols.application.httpv1.HTTPv1> ` ``('HTTP/1',) ``
97+ and :class: `HTTPv2 <pcapkit.protocols.application.httpv2.HTTPv2> `
98+ ``('HTTP/2',) ``
7499 * - Family-inclusive
75100 - the member's label plus the family name
76101 - :class: `~pcapkit.protocols.link.c_tag.C_Tag ` ``('C_Tag', 'VLAN') ``,
77102 :class: `~pcapkit.protocols.link.s_tag.S_Tag ` ``('S_Tag', 'VLAN') ``;
78- :class: `HTTPv1 <pcapkit.protocols.application.httpv1.HTTP> `
79- ``('HTTP', 'HTTPv1') `` and
80- :class: `HTTPv2 <pcapkit.protocols.application.httpv2.HTTP> `
81- ``('HTTP', 'HTTPv2') ``;
82103 :class: `~pcapkit.protocols.link.l2tpv2.L2TPv2 ` ``('L2TP', 'L2TPv2') ``
83104 * - One parser, dynamic alias
84105 - fixed, whichever protocol was read
@@ -99,7 +120,7 @@ A family-inclusive member is selected by any sibling's registry key (a key of
99120``pcapkit.protocols.__proto__ ``), because each expands to the shared family name
100121(:ref: `below <protocol-family-selectors >`). A narrow member is selected by its own name
101122and by the key of each family whose ``id() `` lists it: ``AH `` and ``ESP `` by ``IPsec ``
102- and by ``IPv6_Ext ``.
123+ and by ``IPv6_Ext ``, `` HTTPv1 `` and `` HTTPv2 `` by `` HTTP `` .
103124
104125Chained Records
105126~~~~~~~~~~~~~~~
@@ -142,6 +163,16 @@ them with one. The family base's ``id()`` follows:
142163canonical name and the family's own name are the same string -- the same shape
143164:meth: `ICMP.id() <pcapkit.protocols.internet.icmp.ICMP.id> ` takes, ``('ICMP', 'ICMPv6') ``.
144165
166+ **HTTP takes the RFC names as well ** (:issue: `2524 `). :rfc: `9113 ` names its protocol
167+ ``HTTP/2 ``, so :meth: `HTTPv2.id() <pcapkit.protocols.application.httpv2.HTTPv2.id> ` is
168+ ``('HTTP/2',) ``. :rfc: `9112 ` names ``HTTP/1.1 ``, but the HTTP/1 class also reads
169+ messages declaring 1.0 or 0.9, so
170+ :meth: `HTTPv1.id() <pcapkit.protocols.application.httpv1.HTTPv1.id> ` is the major
171+ version, ``('HTTP/1',) ``, and ``alias `` carries the exact one. No member's name
172+ is the family's, so :meth: `HTTP.id() <pcapkit.protocols.application.http.HTTP.id> `
173+ lists the members alone, ``('HTTP/1', 'HTTP/2') ``, the shape of
174+ :meth: `IP.id() <pcapkit.protocols.internet.ip.IP.id> `.
175+
145176.. _protocol-family-selectors :
146177
147178Selector Matching
@@ -151,6 +182,10 @@ Selector Matching
151182:pr: `2443 `. On an IPv4 frame, ``'IP' in `` is ``True `` and ``'IPv6' in `` is ``False ``.
152183On an IPv6 frame, ``'IP' in `` is ``True `` and ``'IPv4' in `` is ``False ``.
153184
185+ HTTP follows it too (:issue: `2524 `). On an HTTP/1.1 frame, ``'HTTP' in `` and
186+ ``'HTTP/1' in `` are ``True `` and ``'HTTP/2' in `` is ``False ``, since the layer is
187+ :class: `~pcapkit.protocols.application.httpv1.HTTPv1 `; an HTTP/2 frame is the reverse.
188+
154189What a selector on a frame or a layer reaches is defined by
155190:meth: `~pcapkit.protocols.protocol.Protocol.expand_comp `,
156191:meth: `~pcapkit.protocols.protocol.Protocol.__contains__ `,
@@ -161,7 +196,9 @@ Selectors are case-insensitive: ``'ipv4' in`` an IPv4 frame is ``True``.
161196 is not expanded. On a parsed IPv4 layer, ``ipv4 == 'IPv4' `` is ``True `` and
162197 ``ipv4 == 'IP' `` is ``False ``. On a parsed C-Tag layer, ``== 'VLAN' `` is ``True ``,
163198 since ``VLAN `` is in its ``id() ``, and ``== 'S_Tag' `` is ``False ``, though
164- ``'S_Tag' in `` the layer is ``True ``.
199+ ``'S_Tag' in `` the layer is ``True ``. On a parsed HTTP/1.1 layer, ``== 'HTTP/1' `` is
200+ ``True `` and ``== 'HTTP' `` is ``False ``, since no member's ``id() `` carries
201+ ``HTTP ``, though ``'HTTP' in `` the layer is ``True ``.
165202* ``in `` **and ** ``[] `` expand the selector first. A registry key becomes its class
166203 plus that class's ``id() ``, as does a class object, and a layer matches when any of
167204 those appears among its own class and ``id() ``. So ``'S_Tag' in `` a C-Tag frame is
@@ -204,8 +241,6 @@ holds :class:`~pcapkit.protocols.link.linux_sll1.LinuxSLL1`. **The** ``schema/``
204241name, and sub-structure classes such as
205242:class: `~pcapkit.protocols.schema.internet.igmpv3.Query ` share its module. Ruled on
206243:issue: `2529 `, where the classes that do not match yet are pending:
207- :class: `httpv1.HTTP <pcapkit.protocols.application.httpv1.HTTP> `,
208- :class: `httpv2.HTTP <pcapkit.protocols.application.httpv2.HTTP> `,
209244:class: `arp.InARP <pcapkit.protocols.link.arp.InARP> `,
210245:class: `tls.SSLv3 <pcapkit.protocols.application.tls.SSLv3> ` and
211246:class: `null.NoPayload <pcapkit.protocols.misc.null.NoPayload> `.
0 commit comments