refactor(protocols): finish the shared value helpers on ProtocolBase and move TLS onto them

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

@@ -31,7 +31,7 @@ The Order
       :class:`~pcapkit.protocols.internet.mh.MH`, does not count either: it is a
       specific reader, ruled on :issue:`2490`. Each helper's
       ``_read_`` and ``_make_`` methods stay together, with the reader first:
-      ``_read_mac_addr()`` then ``_make_mac_addr()``.
+      ``_read_addr_resolve()`` then ``_make_addr_resolve()``.
    c. **Specific readers and makers.** The option, type and parameter methods,
       all ``_read_*()`` before all ``_make_*()``. Each set opens with the registry's
       default, its fallback for a code with no entry of its own, as
@@ -56,25 +56,37 @@ before its ``_make_xxx()``, and subgroup b, with a table of known exceptions
 Example
 ~~~~~~~
 
-The utilities of :class:`~pcapkit.protocols.link.ethernet.Ethernet`, reduced to
-its member names:
+The utilities of :class:`~pcapkit.protocols.link.arp.ARP`, reduced to its member
+names. ``read()`` resolves a hardware address before a protocol address, so the
+hardware pair comes first:
 
 .. code-block:: python
 
-   class Ethernet(Link[Data_Ethernet, Schema_Ethernet]):
+   class ARP(Link[Data_ARP, Schema_ARP]):
 
        # Utilities.
-       def _make_data(cls, data, ...):      # a. data first
+       def _make_data(cls, data):                    # a. data first
            ...
 
-       def _read_mac_addr(self, ...):       # b. helper: reader ...
+       def _read_addr_resolve(self, addr, htype):    # b. first helper: reader ...
            ...
 
-       def _make_mac_addr(self, ...):       # ... then its maker
+       def _make_addr_resolve(self, addr, htype):    # ... then its maker
+           ...
+
+       def _read_proto_resolve(self, addr, ptype):   # b. next helper: reader ...
+           ...
+
+       def _make_proto_resolve(self, addr, ptype):   # ... then its maker
            ...
 
 The Reference
 ~~~~~~~~~~~~~
 
-:class:`~pcapkit.protocols.link.ethernet.Ethernet` is the reference for the
-utilities order.
+:class:`~pcapkit.protocols.link.arp.ARP` is the reference for the utilities
+order. Its utilities are ``_make_data()`` and the helpers that ``read()`` and
+``make()`` name, and nothing else, and there is more than one helper, so the
+first-use order of subgroup b shows as well as each reader preceding its maker.
+Chosen on :issue:`2614`, when the MAC address pair of
+:class:`~pcapkit.protocols.link.ethernet.Ethernet`, the reference before it,
+moved to the base class.

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

@@ -38,8 +38,6 @@ below:
 
    .. automethod:: __index__
 
-   .. automethod:: _make_mac_addr
-
 Header Schemas
 --------------
 

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

@@ -70,14 +70,13 @@ Scope
    .. automethod:: _make_data
    .. automethod:: _read_frame_control
    .. automethod:: _make_frame_control
-   .. automethod:: _read_mac_addr
-   .. automethod:: _make_mac_addr
    .. automethod:: _read_seq_ctrl
    .. automethod:: _make_seq_ctrl
    .. automethod:: _read_qos_control
    .. automethod:: _make_qos_control
    .. automethod:: _read_ht_control
    .. automethod:: _make_ht_control
+   .. automethod:: _make_mac_addr
 
 .. autodata:: pcapkit.protocols.link.ieee802_11.SUBTYPE
    :no-value:

docs/source/pcapkit/protocols/protocol.rst

@@ -83,6 +83,9 @@ Internal Definitions below.
    .. automethod:: _make_payload
    .. automethod:: _packing_target
 
+   .. automethod:: _read_mac_addr
+   .. automethod:: _make_mac_addr
+
    .. automethod:: _lookup_registry
    .. automethod:: _lookup_next_layer
    .. automethod:: _decode_next_layer
@@ -198,6 +201,8 @@ Internal Definitions
                   _make_index
                   _make_payload
                   _packing_target
+                  _read_mac_addr
+                  _make_mac_addr
                   _lookup_registry
                   _lookup_next_layer
                   _decode_next_layer
@@ -223,7 +228,8 @@ Internal Definitions
       :meth:`~Protocol.expand_comp`, :meth:`~Protocol._read_packet`,
       :meth:`~Protocol._get_payload`, :meth:`~Protocol._make_data`,
       :meth:`~Protocol._make_index`, :meth:`~Protocol._make_payload`,
-      :meth:`~Protocol._packing_target`,
+      :meth:`~Protocol._packing_target`, :meth:`~Protocol._read_mac_addr`,
+      :meth:`~Protocol._make_mac_addr`,
       :meth:`~Protocol._lookup_registry`, :meth:`~Protocol._lookup_next_layer`,
       :meth:`~Protocol._decode_next_layer`,
       :meth:`~Protocol._import_next_layer`,

pcapkit/protocols/application/dtls.py

@@ -499,12 +499,20 @@ def make(self,
         Raises:
             ProtocolError: If ``cid`` is missing or invalid for a ``tls12_cid``
                 record, or given for any other.
+            StructError: If a record-header field, or a field of ``content``,
+                does not fit its width.
+            FieldValueError: If a unified-header record's ``epoch`` does not
+                fit its two bits.
 
         """
         self._learn_payload_connection_ids(payload)
         if ciphertext:
             if cid is not None:
                 raise ProtocolError(f'{self.alias}: invalid connection ID: only a tls12_cid record carries one')
+            # NOTE: packed first for the reason below; ``epoch`` is a bit sub-field the schema refuses itself.
+            self._make_pack(sequence_number, size=2 if sequence_long else 1)
+            if length_present:
+                self._make_pack(len(content), size=2)
             return Schema_DTLSCiphertext(
                 flags={
                     'fixed': _UNIFIED_PREFIX,
@@ -524,6 +532,11 @@ def make(self,
             reversed=content_type_reversed, pack=False))
 
         fragment = data if data is not None else self._make_tls_content(content_type_, content, dtls=True)
+        # NOTE: the schema masks a field to its width, so each is packed here first, to
+        # refuse a wider value with the StructError the content makers raise.
+        for value, size in ((int(content_type_), 1), (version, 2), (epoch, 2), (len(fragment), 2)):
+            self._make_pack(value, size=size)
+        self._make_pack(sequence_number, size=6)
         if int(content_type_) == Enum_ContentType.tls12_cid:
             if cid is None or not _is_cid(cid):
                 raise ProtocolError(f'{self.alias}: invalid connection ID: {cid!r} '

pcapkit/protocols/application/ospf.py

@@ -326,9 +326,9 @@ def make(self,
 
         if packet_length is None:
             packet_length = 24 + len(payload)
-        elif (not isinstance(packet_length, int) or isinstance(packet_length, bool)
-              or not 0 <= packet_length <= 0xFFFF):
-            raise ProtocolError(f'OSPF: invalid packet length: {packet_length!r}')
+        else:
+            # NOTE: ``alias`` reads ``_version``, which only ``read()`` sets.
+            packet_length = self._make_uint(packet_length, bits=16, name='packet length', alias='OSPF')
 
         schema = Schema_OSPF(
             version=version,