refactor(application)!: dispatch HTTP to HTTPv1/HTTPv2 under the RFC names (#2524)

docs/source/contributing/conventions/protocol-family-grouping.rst

@@ -21,12 +21,12 @@ The member list takes either of these forms:
   :class:`~pcapkit.protocols.internet.esp.ESP` are not in it, since they belong to
   the separate abstract :class:`~pcapkit.protocols.internet.ipsec.IPsec`, whose
   :meth:`~pcapkit.protocols.internet.ipsec.IPsec.id` is ``('AH', 'ESP')``.
+  :meth:`HTTP.id() <pcapkit.protocols.application.http.HTTP.id>` is
+  ``('HTTP/1', 'HTTP/2')``.
 * **The base's own name, then the members.**
   :meth:`VLAN.id() <pcapkit.protocols.link.vlan.VLAN.id>` is
-  ``('VLAN', 'C_Tag', 'S_Tag')``,
-  :meth:`L2TP.id() <pcapkit.protocols.link.l2tp.L2TP.id>` is ``('L2TP', 'L2TPv2')``
-  and :meth:`HTTP.id() <pcapkit.protocols.application.http.HTTP.id>` is
-  ``('HTTP', 'HTTPv1', 'HTTPv2')``.
+  ``('VLAN', 'C_Tag', 'S_Tag')`` and
+  :meth:`L2TP.id() <pcapkit.protocols.link.l2tp.L2TP.id>` is ``('L2TP', 'L2TPv2')``.
 
 :meth:`ARP.id() <pcapkit.protocols.link.arp.ARP.id>` is ``('ARP',)`` alone; see
 :ref:`protocol-family-shapes`.
@@ -48,7 +48,29 @@ HTTP/2 share :class:`~pcapkit.protocols.application.http.HTTP`, IPv4 and IPv6 sh
 
 :class:`~pcapkit.protocols.internet.ip.IP` and
 :class:`~pcapkit.protocols.internet.ipsec.IPsec` define no ``read()``. The HTTP class
-does, and a parsed HTTP/1.1 or HTTP/2 layer is the HTTP class itself.
+does, but yields no instance of itself (:ref:`below <protocol-family-dispatch>`).
+
+.. _protocol-family-dispatch:
+
+Dispatching Bases
+~~~~~~~~~~~~~~~~~
+
+**A versioned family's base dispatches on both paths** (:issue:`2524`). Parsing
+octets through it, constructing it from fields and its ``from_data`` give the member
+the octets, fields or data model describe, never an instance of the base. In
+:class:`~pcapkit.protocols.application.http.HTTP`,
+:meth:`~pcapkit.protocols.application.http.HTTP._dispatch_version` picks the member
+from the octets, for a payload a transport port binds to HTTP as well, and
+:meth:`~pcapkit.protocols.application.http.HTTP._dispatch_fields` from the fields.
+The other versioned families are tracked on :issue:`2574`.
+
+**Octets neither version takes**, a frameless HTTP/2 connection preface among them,
+are :class:`~pcapkit.protocols.misc.raw.Raw` with no ``error`` on the transport path,
+and a direct ``HTTP(...)`` on them raises
+:exc:`~pcapkit.utilities.exceptions.ProtocolError` (:issue:`2524`). Octets the
+dispatcher gives :class:`~pcapkit.protocols.application.httpv2.HTTPv2` that its parser
+then refuses, such as a preface and three octets, are
+:class:`~pcapkit.protocols.misc.raw.Raw` with the parser's ``error``.
 
 .. _protocol-family-shapes:
 
@@ -70,15 +92,14 @@ Member Shapes
        :class:`IGMPv3 <pcapkit.protocols.internet.igmpv3.IGMPv3>` ``('IGMPv3',)`` --
        :class:`IGMPv1 <pcapkit.protocols.internet.igmpv1.IGMPv1>` narrows the same way,
        but to the RFC canonical name rather than a versioned one
-       (:ref:`protocol-family-canonical-names`)
+       (:ref:`protocol-family-canonical-names`);
+       :class:`HTTPv1 <pcapkit.protocols.application.httpv1.HTTPv1>` ``('HTTP/1',)``
+       and :class:`HTTPv2 <pcapkit.protocols.application.httpv2.HTTPv2>`
+       ``('HTTP/2',)``
    * - Family-inclusive
      - the member's label plus the family name
      - :class:`~pcapkit.protocols.link.c_tag.C_Tag` ``('C_Tag', 'VLAN')``,
        :class:`~pcapkit.protocols.link.s_tag.S_Tag` ``('S_Tag', 'VLAN')``;
-       :class:`HTTPv1 <pcapkit.protocols.application.httpv1.HTTP>`
-       ``('HTTP', 'HTTPv1')`` and
-       :class:`HTTPv2 <pcapkit.protocols.application.httpv2.HTTP>`
-       ``('HTTP', 'HTTPv2')``;
        :class:`~pcapkit.protocols.link.l2tpv2.L2TPv2` ``('L2TP', 'L2TPv2')``
    * - One parser, dynamic alias
      - fixed, whichever protocol was read
@@ -99,7 +120,7 @@ A family-inclusive member is selected by any sibling's registry key (a key of
 ``pcapkit.protocols.__proto__``), because each expands to the shared family name
 (:ref:`below <protocol-family-selectors>`). A narrow member is selected by its own name
 and by the key of each family whose ``id()`` lists it: ``AH`` and ``ESP`` by ``IPsec``
-and by ``IPv6_Ext``.
+and by ``IPv6_Ext``, ``HTTPv1`` and ``HTTPv2`` by ``HTTP``.
 
 Chained Records
 ~~~~~~~~~~~~~~~
@@ -142,6 +163,16 @@ them with one. The family base's ``id()`` follows:
 canonical name and the family's own name are the same string -- the same shape
 :meth:`ICMP.id() <pcapkit.protocols.internet.icmp.ICMP.id>` takes, ``('ICMP', 'ICMPv6')``.
 
+**HTTP takes the RFC names as well** (:issue:`2524`). :rfc:`9113` names its protocol
+``HTTP/2``, so :meth:`HTTPv2.id() <pcapkit.protocols.application.httpv2.HTTPv2.id>` is
+``('HTTP/2',)``. :rfc:`9112` names ``HTTP/1.1``, but the HTTP/1 class also reads
+messages declaring 1.0 or 0.9, so
+:meth:`HTTPv1.id() <pcapkit.protocols.application.httpv1.HTTPv1.id>` is the major
+version, ``('HTTP/1',)``, and ``alias`` carries the exact one. No member's name
+is the family's, so :meth:`HTTP.id() <pcapkit.protocols.application.http.HTTP.id>`
+lists the members alone, ``('HTTP/1', 'HTTP/2')``, the shape of
+:meth:`IP.id() <pcapkit.protocols.internet.ip.IP.id>`.
+
 .. _protocol-family-selectors:
 
 Selector Matching
@@ -151,6 +182,10 @@ Selector Matching
 :pr:`2443`. On an IPv4 frame, ``'IP' in`` is ``True`` and ``'IPv6' in`` is ``False``.
 On an IPv6 frame, ``'IP' in`` is ``True`` and ``'IPv4' in`` is ``False``.
 
+HTTP follows it too (:issue:`2524`). On an HTTP/1.1 frame, ``'HTTP' in`` and
+``'HTTP/1' in`` are ``True`` and ``'HTTP/2' in`` is ``False``, since the layer is
+:class:`~pcapkit.protocols.application.httpv1.HTTPv1`; an HTTP/2 frame is the reverse.
+
 What a selector on a frame or a layer reaches is defined by
 :meth:`~pcapkit.protocols.protocol.Protocol.expand_comp`,
 :meth:`~pcapkit.protocols.protocol.Protocol.__contains__`,
@@ -161,7 +196,9 @@ Selectors are case-insensitive: ``'ipv4' in`` an IPv4 frame is ``True``.
   is not expanded. On a parsed IPv4 layer, ``ipv4 == 'IPv4'`` is ``True`` and
   ``ipv4 == 'IP'`` is ``False``. On a parsed C-Tag layer, ``== 'VLAN'`` is ``True``,
   since ``VLAN`` is in its ``id()``, and ``== 'S_Tag'`` is ``False``, though
-  ``'S_Tag' in`` the layer is ``True``.
+  ``'S_Tag' in`` the layer is ``True``. On a parsed HTTP/1.1 layer, ``== 'HTTP/1'`` is
+  ``True`` and ``== 'HTTP'`` is ``False``, since no member's ``id()`` carries
+  ``HTTP``, though ``'HTTP' in`` the layer is ``True``.
 * ``in`` **and** ``[]`` expand the selector first. A registry key becomes its class
   plus that class's ``id()``, as does a class object, and a layer matches when any of
   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/``
 name, and sub-structure classes such as
 :class:`~pcapkit.protocols.schema.internet.igmpv3.Query` share its module. Ruled on
 :issue:`2529`, where the classes that do not match yet are pending:
-:class:`httpv1.HTTP <pcapkit.protocols.application.httpv1.HTTP>`,
-:class:`httpv2.HTTP <pcapkit.protocols.application.httpv2.HTTP>`,
 :class:`arp.InARP <pcapkit.protocols.link.arp.InARP>`,
 :class:`tls.SSLv3 <pcapkit.protocols.application.tls.SSLv3>` and
 :class:`null.NoPayload <pcapkit.protocols.misc.null.NoPayload>`.

docs/source/contributing/conventions/protocol-member-order.rst

@@ -41,7 +41,7 @@ The Order
       :issue:`2490`.
    d. **Other helpers.** Every helper that ``read()``, ``make()`` and the registries
       do not reach goes last, including one that only another helper calls, such as
-      ``_decode_text()`` in :class:`~pcapkit.protocols.application.httpv1.HTTP`.
+      ``_decode_text()`` in :class:`~pcapkit.protocols.application.httpv1.HTTPv1`.
       Ruled on :issue:`2490`.
 
 **Registry maps.** The registry maps themselves (``__proto__``, ``__option__``,

docs/source/contributing/pep.rst

@@ -361,7 +361,7 @@ Follow-ups to the bindings above:
   <pcapkit.protocols.transport.tcp.TCP.__proto__>` and :attr:`UDP.__proto__
   <pcapkit.protocols.transport.udp.UDP.__proto__>` both point their HTTP ports at
   the version-identifying proxy :class:`pcapkit.protocols.application.http.HTTP`
-  rather than at :class:`pcapkit.protocols.application.httpv1.HTTP`, so a
+  rather than at :class:`pcapkit.protocols.application.httpv1.HTTPv1`, so a
   segment's HTTP version is decided by its payload rather than asserted by its
   port number. That depends on the proxy identifying the version positively
   instead of guessing, since a guess path is wrong on non-HTTP input.

docs/source/ext.rst

@@ -98,9 +98,9 @@ The protocol classes :mod:`pcapkit` ships:
 + Application Layer                                                +----------------+-----------------------+-------------------------------------------------------------+
 | (:class:`~pcapkit.protocols.application.application.Application` |                | :class:`pcapkit.protocols.application.http.HTTP`                                    |
 + subclasses)                                                      +                +-----------------------+-------------------------------------------------------------+
-|                                                                  | HTTP Family    | :class:`pcapkit.protocols.application.httpv1.HTTP`                                  |
+|                                                                  | HTTP Family    | :class:`pcapkit.protocols.application.httpv1.HTTPv1`                                |
 +                                                                  +                +-----------------------+-------------------------------------------------------------+
-|                                                                  |                | :class:`pcapkit.protocols.application.httpv2.HTTP`                                  |
+|                                                                  |                | :class:`pcapkit.protocols.application.httpv2.HTTPv2`                                |
 +                                                                  +----------------+-----------------------+-------------------------------------------------------------+
 |                                                                  | :class:`pcapkit.protocols.application.ngap.NGAP`                                                     |
 +                                                                  +----------------+-----------------------+-------------------------------------------------------------+
@@ -406,7 +406,7 @@ writes them:
 +                   +                                                            +-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------+
 |                   |                                                            | :attr:`SCTP.__cause__ <pcapkit.protocols.transport.sctp.SCTP.__cause__>`                      | :func:`~pcapkit.foundation.registry.protocols.register_sctp_cause`         |
 +-------------------+------------------------------------------------------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------+
-| Application Layer | :class:`~pcapkit.protocols.application.httpv2.HTTP`        | :attr:`HTTP.__frame__ <pcapkit.protocols.application.httpv2.HTTP.__frame__>`                  | :func:`~pcapkit.foundation.registry.protocols.register_http_frame`         |
+| Application Layer | :class:`~pcapkit.protocols.application.httpv2.HTTPv2`      | :attr:`HTTPv2.__frame__ <pcapkit.protocols.application.httpv2.HTTPv2.__frame__>`              | :func:`~pcapkit.foundation.registry.protocols.register_http_frame`         |
 +-------------------+------------------------------------------------------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------+
 |                   |                                                            | :attr:`PCAPNG.__block__ <pcapkit.protocols.misc.pcapng.PCAPNG.__block__>`                     | :func:`~pcapkit.foundation.registry.protocols.register_pcapng_block`       |
 +                   +                                                            +-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------+

docs/source/pcapkit/protocols/application/application.rst

@@ -6,8 +6,8 @@ Application Layer Base Protocol
 :mod:`pcapkit.protocols.application.application` contains only
 :class:`~pcapkit.protocols.application.application.Application`,
 which is a base class for application layer protocols, e.g.
-:class:`HTTP/1.* <pcapkit.protocols.application.httpv1.HTTP>` and
-:class:`HTTP/2 <pcapkit.protocols.application.httpv2.HTTP>`.
+:class:`HTTP/1.* <pcapkit.protocols.application.httpv1.HTTPv1>` and
+:class:`HTTP/2 <pcapkit.protocols.application.httpv2.HTTPv2>`.
 
 .. versionchanged:: 1.5.0
 

docs/source/pcapkit/protocols/application/http.rst

@@ -7,11 +7,21 @@ HTTP - Hypertext Transfer Protocol
 :class:`~pcapkit.protocols.application.http.HTTP`,
 which is a base class for Hypertext Transfer
 Protocol (HTTP) [*]_ family, e.g.
-:class:`HTTP/1.* <pcapkit.protocols.application.httpv1.HTTP>`
-and :class:`HTTP/2 <pcapkit.protocols.application.httpv2.HTTP>`,
+:class:`HTTP/1.* <pcapkit.protocols.application.httpv1.HTTPv1>`
+and :class:`HTTP/2 <pcapkit.protocols.application.httpv2.HTTPv2>`,
 and :func:`~pcapkit.protocols.application.http.test_start_line`,
 which tells whether a payload opens with an HTTP/1.* start line.
 
+.. versionchanged:: 1.6.0
+
+   A payload a transport port binds to
+   :class:`~pcapkit.protocols.application.http.HTTP`, and constructing or
+   rebuilding that class, give
+   :class:`~pcapkit.protocols.application.httpv1.HTTPv1` or
+   :class:`~pcapkit.protocols.application.httpv2.HTTPv2` rather than an instance
+   of it, so the data sits under ``httpv1`` or ``httpv2`` rather than ``http``
+   (:issue:`2524`).
+
 .. autoclass:: pcapkit.protocols.application.http.HTTP
    :no-members:
    :show-inheritance:
@@ -28,7 +38,12 @@ which tells whether a payload opens with an HTTP/1.* start line.
 
    .. automethod:: _make_data
 
+   .. automethod:: __new__
+
    .. automethod:: _guess_version
+   .. automethod:: _dispatch_version
+   .. automethod:: _dispatch_fields
+   .. automethod:: _member_of_version
 
    .. autoattribute:: _preface_length
 

docs/source/pcapkit/protocols/application/httpv1.rst

@@ -4,7 +4,7 @@ HTTP/1.* - Hypertext Transfer Protocol
 .. module:: pcapkit.protocols.application.httpv1
 
 :mod:`pcapkit.protocols.application.httpv1` contains
-:class:`~pcapkit.protocols.application.httpv1.HTTP`,
+:class:`~pcapkit.protocols.application.httpv1.HTTPv1`,
 which implements an extractor for Hypertext Transfer
 Protocol (HTTP/1.*) [*]_, and its
 :class:`~pcapkit.protocols.application.httpv1.Type` enumeration. The
@@ -31,7 +31,13 @@ structure of an HTTP/1.* message is described as below:
    rather than normalised or re-encoded (:issue:`1241`, :issue:`1302`,
    :issue:`1333`).
 
-.. autoclass:: pcapkit.protocols.application.httpv1.HTTP
+.. versionremoved:: 1.6.0
+
+   ``pcapkit.protocols.application.httpv1.HTTP``, with no alias. The
+   class is renamed :class:`~pcapkit.protocols.application.httpv1.HTTPv1`,
+   after its module (:issue:`2529`).
+
+.. autoclass:: pcapkit.protocols.application.httpv1.HTTPv1
    :no-members:
    :show-inheritance:
 
@@ -60,7 +66,13 @@ Header Schemas
 
 .. module:: pcapkit.protocols.schema.application.httpv1
 
-.. autoclass:: pcapkit.protocols.schema.application.httpv1.HTTP
+.. versionremoved:: 1.6.0
+
+   ``pcapkit.protocols.schema.application.httpv1.HTTP``, with no alias. The
+   class is renamed :class:`~pcapkit.protocols.schema.application.httpv1.HTTPv1`,
+   after its module (:issue:`2529`).
+
+.. autoclass:: pcapkit.protocols.schema.application.httpv1.HTTPv1
    :members:
    :show-inheritance:
 
@@ -69,7 +81,13 @@ Data Models
 
 .. module:: pcapkit.protocols.data.application.httpv1
 
-.. autoclass:: pcapkit.protocols.data.application.httpv1.HTTP
+.. versionremoved:: 1.6.0
+
+   ``pcapkit.protocols.data.application.httpv1.HTTP``, with no alias. The
+   class is renamed :class:`~pcapkit.protocols.data.application.httpv1.HTTPv1`,
+   after its module (:issue:`2529`).
+
+.. autoclass:: pcapkit.protocols.data.application.httpv1.HTTPv1
    :members:
    :show-inheritance:
 

docs/source/pcapkit/protocols/application/httpv2.rst

@@ -4,7 +4,7 @@ HTTP/2 - Hypertext Transfer Protocol
 .. module:: pcapkit.protocols.application.httpv2
 
 :mod:`pcapkit.protocols.application.httpv2` contains
-:class:`~pcapkit.protocols.application.httpv2.HTTP`
+:class:`~pcapkit.protocols.application.httpv2.HTTPv2`
 only, which implements an extractor for Hypertext Transfer
 Protocol (HTTP/2) [*]_, whose structure is described as
 below:
@@ -31,11 +31,17 @@ Octets      Bits        Name                    Description
    are kept (:issue:`652`, :issue:`668`, :issue:`1244`, :issue:`1245`,
    :issue:`1246`, :issue:`1247`).
 
+.. versionremoved:: 1.6.0
+
+   ``pcapkit.protocols.application.httpv2.HTTP``, with no alias. The
+   class is renamed :class:`~pcapkit.protocols.application.httpv2.HTTPv2`,
+   after its module (:issue:`2529`).
+
 .. raw:: html
 
    <br />
 
-.. autoclass:: pcapkit.protocols.application.httpv2.HTTP
+.. autoclass:: pcapkit.protocols.application.httpv2.HTTPv2
    :no-members:
    :show-inheritance:
 
@@ -85,7 +91,13 @@ Header Schemas
 
 .. module:: pcapkit.protocols.schema.application.httpv2
 
-.. autoclass:: pcapkit.protocols.schema.application.httpv2.HTTP
+.. versionremoved:: 1.6.0
+
+   ``pcapkit.protocols.schema.application.httpv2.HTTP``, with no alias. The
+   class is renamed :class:`~pcapkit.protocols.schema.application.httpv2.HTTPv2`,
+   after its module (:issue:`2529`).
+
+.. autoclass:: pcapkit.protocols.schema.application.httpv2.HTTPv2
    :members:
    :show-inheritance:
 
@@ -170,7 +182,13 @@ Data Models
 
 .. module:: pcapkit.protocols.data.application.httpv2
 
-.. autoclass:: pcapkit.protocols.data.application.httpv2.HTTP
+.. versionremoved:: 1.6.0
+
+   ``pcapkit.protocols.data.application.httpv2.HTTP``, with no alias. The
+   class is renamed :class:`~pcapkit.protocols.data.application.httpv2.HTTPv2`,
+   after its module (:issue:`2529`).
+
+.. autoclass:: pcapkit.protocols.data.application.httpv2.HTTPv2
    :members:
    :show-inheritance:
 

docs/source/pcapkit/protocols/index.rst

@@ -174,8 +174,8 @@ from given information. The class hierarchy of :mod:`pcapkit.protocols`:
 
        click Application "application/application.html#pcapkit.protocols.application.application.Application"
        click HTTP "application/http.html#pcapkit.protocols.application.http.HTTP"
-       click h1 "application/httpv1.html#pcapkit.protocols.application.httpv1.HTTP"
-       click h2 "application/httpv2.html#pcapkit.protocols.application.httpv2.HTTP"
+       click h1 "application/httpv1.html#pcapkit.protocols.application.httpv1.HTTPv1"
+       click h2 "application/httpv2.html#pcapkit.protocols.application.httpv2.HTTPv2"
        click FTP "application/ftp.html#pcapkit.protocols.application.ftp.FTP"
        click FTP_DATA "application/ftp_data.html#pcapkit.protocols.application.ftp_data.FTP_DATA"
        click NGAP "application/ngap.html#pcapkit.protocols.application.ngap.NGAP"

docs/source/pcapkit/protocols/link/l2tp.rst

@@ -53,7 +53,7 @@ the value 1 "to permit detection of L2F packets should they arrive intermixed wi
 L2TP packets". L2F is a separate protocol with its own header, so it is to be
 implemented as ``L2F``, the canonical name, with ``L2TPv1`` only as an alias in its
 :meth:`~pcapkit.protocols.protocol.Protocol.id`. See
-:meth:`HTTPv1.id <pcapkit.protocols.application.httpv1.HTTP.id>` for
+:meth:`L2TPv2.id <pcapkit.protocols.link.l2tpv2.L2TPv2.id>` for
 how a version-flavoured alias is spelled: canonical name first, alias second,
 since callers take element zero as canonical.