use new exception type for data protocol errors

Author: Kriechi

CHANGELOG.rst

@@ -4,6 +4,16 @@ Release History
 6.0.0+dev
 ---------
 
+**Backwards Incompatible API Changes**
+
+- Introduce ``HyperframeError`` base exception class for all errors raised within hyperframe.
+- Change exception base class of ``UnknownFrameError`` to ``HyperframeError``
+- Change exception base class of ``InvalidPaddingError`` to ``HyperframeError``
+- Change exception base class of ``InvalidFrameError`` to ``HyperframeError``
+- Invalid frames with wrong stream id (zero vs. non-zero) now raise ``InvalidDataError``.
+- Invalid SETTINGS frames (non-empty but ACK) now raise ``InvalidDataError``.
+- Invalid ALTSVC frames with non-bytestring field or origin now raise ``InvalidDataError``.
+
 **API Changes (Backward-compatible)**
 
 - Deprecate ``total_padding`` - use `pad_length` instead.
@@ -12,16 +22,10 @@ Release History
 
 - Fixed padding parsing for ``PushPromiseFrame``.
 - Fixed unchecked frame length for ``PriorityFrame``. It now correctly raises ``InvalidFrameError``.
-- Fixed promised stream id parsing for ``PushPromiseFrame``.
+- Fixed promised stream id validation for ``PushPromiseFrame``. It now raises ``InvalidDataError``.
 - Fixed unchecked frame length for ``WindowUpdateFrame``. It now correctly raises ``InvalidFrameError``.
-- Fixed window increment value range validation. It must be 1 <= increment <= 2^31-1.
+- Fixed window increment value range validation. It now raises ``InvalidDataError``.
 - Fixed parsing of ``SettingsFrame`` with mutual exclusion of ACK flag and payload.
-- Invalid frames with wrong stream id (zero vs. non-zero) now raise ``InvalidFrameError``, not
-  ``ValueError``. Note that ``InvalidFrameError`` is a ``ValueError`` subclass.
-- Invalid SETTINGS frames (non-empty but ACK) now raise ``InvalidFrameError``, not
-  ``ValueError``. Note that ``InvalidFrameError`` is a ``ValueError`` subclass.
-- Invalid ALTSVC frames with non-bytestring field or origin now raise ``InvalidFrameError``, not
-  ``ValueError``. Note that ``InvalidFrameError`` is a ``ValueError`` subclass.
 
 **Other Changes**
 

docs/source/api.rst

@@ -72,6 +72,9 @@ you need is not present!
 Exceptions
 ----------
 
+.. autoclass:: hyperframe.exceptions.HyperframeError
+   :members:
+
 .. autoclass:: hyperframe.exceptions.UnknownFrameError
    :members:
 
@@ -80,3 +83,6 @@ Exceptions
 
 .. autoclass:: hyperframe.exceptions.InvalidFrameError
    :members:
+
+.. autoclass:: hyperframe.exceptions.InvalidDataError
+   :members:

src/hyperframe/exceptions.py

@@ -7,9 +7,20 @@
 """
 
 
-class UnknownFrameError(ValueError):
+class HyperframeError(Exception):
+    """
+    The base class for all exceptions for the hyperframe module.
+
+    .. versionadded:: 6.0.0
+    """
+
+
+class UnknownFrameError(HyperframeError):
     """
     A frame of unknown type was received.
+
+    .. versionchanged:: 6.0.0
+        Changed base class from `ValueError` to :class:`HyperframeError`
     """
     def __init__(self, frame_type, length):
         #: The type byte of the unknown frame that was received.
@@ -25,17 +36,32 @@ def __str__(self):
         )
 
 
-class InvalidPaddingError(ValueError):
+class InvalidPaddingError(HyperframeError):
     """
     A frame with invalid padding was received.
+
+    .. versionchanged:: 6.0.0
+        Changed base class from `ValueError` to :class:`HyperframeError`
     """
     pass
 
 
-class InvalidFrameError(ValueError):
+class InvalidFrameError(HyperframeError):
     """
     Parsing a frame failed because the data was not laid out appropriately.
 
     .. versionadded:: 3.0.2
+
+    .. versionchanged:: 6.0.0
+        Changed base class from `ValueError` to :class:`HyperframeError`
+    """
+    pass
+
+
+class InvalidDataError(HyperframeError):
+    """
+    Content or data of a frame was is invalid or violates the specification.
+
+    .. versionadded:: 6.0.0
     """
     pass

src/hyperframe/frame.py

@@ -11,7 +11,7 @@
 import binascii
 
 from .exceptions import (
-    UnknownFrameError, InvalidPaddingError, InvalidFrameError
+    UnknownFrameError, InvalidPaddingError, InvalidFrameError, InvalidDataError
 )
 from .flags import Flag, Flags
 
@@ -68,10 +68,10 @@ def __init__(self, stream_id, flags=()):
 
         if (not self.stream_id and
            self.stream_association == _STREAM_ASSOC_HAS_STREAM):
-            raise InvalidFrameError('Stream ID must be non-zero')
+            raise InvalidDataError('Stream ID must be non-zero')
         if (self.stream_id and
            self.stream_association == _STREAM_ASSOC_NO_STREAM):
-            raise InvalidFrameError('Stream ID must be zero')
+            raise InvalidDataError('Stream ID must be zero')
 
     def __repr__(self):
         flags = ", ".join(self.flags) or "None"
@@ -84,7 +84,7 @@ def __repr__(self):
             type=type(self).__name__,
             stream=self.stream_id,
             flags=flags,
-            body=body
+            body=body,
         )
 
     @staticmethod
@@ -95,6 +95,9 @@ def parse_frame_header(header, strict=False):
 
         This populates the flags field, and determines how long the body is.
 
+        :param header: A memoryview object containing the 9-byte frame header
+                       data of a frame. Must not contain more or less.
+
         :param strict: Whether to raise an exception when encountering a frame
             not defined by spec and implemented by hyperframe.
 
@@ -415,7 +418,7 @@ def __init__(self, stream_id=0, settings=None, **kwargs):
         super().__init__(stream_id, **kwargs)
 
         if settings and "ACK" in kwargs.get("flags", ()):
-            raise InvalidFrameError(
+            raise InvalidDataError(
                 "Settings must be empty if ACK flag is set."
             )
 
@@ -428,7 +431,7 @@ def serialize_body(self):
 
     def parse_body(self, data):
         if 'ACK' in self.flags and len(data) > 0:
-            raise InvalidFrameError(
+            raise InvalidDataError(
                 "SETTINGS ack frame must not have payload: got %s bytes" %
                 len(data)
             )
@@ -494,7 +497,7 @@ def parse_body(self, data):
         self.body_len = len(data)
 
         if self.promised_stream_id == 0 or self.promised_stream_id % 2 != 0:
-            raise InvalidFrameError(
+            raise InvalidDataError(
                 "Invalid PUSH_PROMISE promised stream id: %s" %
                 self.promised_stream_id
             )
@@ -642,7 +645,7 @@ def parse_body(self, data):
             raise InvalidFrameError("Invalid WINDOW_UPDATE body")
 
         if not 1 <= self.window_increment <= 2**31-1:
-            raise InvalidFrameError(
+            raise InvalidDataError(
                 "WINDOW_UPDATE increment must be between 1 to 2^31-1"
             )
 
@@ -764,9 +767,9 @@ def __init__(self, stream_id, origin=b'', field=b'', **kwargs):
         super().__init__(stream_id, **kwargs)
 
         if not isinstance(origin, bytes):
-            raise InvalidFrameError("AltSvc origin must be bytestring.")
+            raise InvalidDataError("AltSvc origin must be bytestring.")
         if not isinstance(field, bytes):
-            raise InvalidFrameError("AltSvc field must be a bytestring.")
+            raise InvalidDataError("AltSvc field must be a bytestring.")
         self.origin = origin
         self.field = field
 

test/test_frames.py

@@ -5,7 +5,7 @@
     ContinuationFrame, AltSvcFrame, ExtensionFrame
 )
 from hyperframe.exceptions import (
-    UnknownFrameError, InvalidPaddingError, InvalidFrameError
+    UnknownFrameError, InvalidPaddingError, InvalidFrameError, InvalidDataError
 )
 import pytest
 
@@ -179,7 +179,7 @@ def test_data_frame_without_padding_calculates_flow_control_len(self):
         assert f.flow_controlled_length == 8
 
     def test_data_frame_comes_on_a_stream(self):
-        with pytest.raises(InvalidFrameError):
+        with pytest.raises(InvalidDataError):
             DataFrame(0)
 
     def test_long_data_frame(self):
@@ -269,7 +269,7 @@ def test_priority_frame_invalid(self):
             )
 
     def test_priority_frame_comes_on_a_stream(self):
-        with pytest.raises(InvalidFrameError):
+        with pytest.raises(InvalidDataError):
             PriorityFrame(0)
 
     def test_short_priority_frame_errors(self):
@@ -301,7 +301,7 @@ def test_rst_stream_frame_parses_properly(self):
         assert f.body_len == 4
 
     def test_rst_stream_frame_comes_on_a_stream(self):
-        with pytest.raises(InvalidFrameError):
+        with pytest.raises(InvalidDataError):
             RstStreamFrame(0)
 
     def test_rst_stream_frame_must_have_body_length_four(self):
@@ -358,10 +358,10 @@ def test_settings_frame_with_ack(self):
         assert 'ACK' in f.flags
 
     def test_settings_frame_ack_and_settings(self):
-        with pytest.raises(InvalidFrameError):
+        with pytest.raises(InvalidDataError):
             SettingsFrame(settings=self.settings, flags=('ACK',))
 
-        with pytest.raises(InvalidFrameError):
+        with pytest.raises(InvalidDataError):
             decode_frame(self.serialized)
 
     def test_settings_frame_parses_properly(self):
@@ -382,11 +382,11 @@ def test_settings_frame_invalid_body_length(self):
             )
 
     def test_settings_frames_never_have_streams(self):
-        with pytest.raises(InvalidFrameError):
+        with pytest.raises(InvalidDataError):
             SettingsFrame(stream_id=1)
 
     def test_short_settings_frame_errors(self):
-        with pytest.raises(InvalidFrameError):
+        with pytest.raises(InvalidDataError):
             decode_frame(self.serialized[:-2])
 
 
@@ -458,11 +458,11 @@ def test_push_promise_frame_with_no_length_parses(self):
 
     def test_push_promise_frame_invalid(self):
         data = PushPromiseFrame(1, 0).serialize()
-        with pytest.raises(InvalidFrameError):
+        with pytest.raises(InvalidDataError):
             decode_frame(data)
 
         data = PushPromiseFrame(1, 3).serialize()
-        with pytest.raises(InvalidFrameError):
+        with pytest.raises(InvalidDataError):
             decode_frame(data)
 
     def test_short_push_promise_errors(self):
@@ -513,7 +513,7 @@ def test_ping_frame_parses_properly(self):
         assert f.body_len == 8
 
     def test_ping_frame_never_has_a_stream(self):
-        with pytest.raises(InvalidFrameError):
+        with pytest.raises(InvalidDataError):
             PingFrame(stream_id=1)
 
     def test_ping_frame_has_no_more_than_body_length_8(self):
@@ -577,7 +577,7 @@ def test_goaway_frame_parses_properly(self):
         assert f.body_len == 8
 
     def test_goaway_frame_never_has_a_stream(self):
-        with pytest.raises(InvalidFrameError):
+        with pytest.raises(InvalidDataError):
             GoAwayFrame(stream_id=1)
 
     def test_short_goaway_frame_errors(self):
@@ -623,10 +623,10 @@ def test_short_windowupdate_frame_errors(self):
         with pytest.raises(InvalidFrameError):
             decode_frame(s)
 
-        with pytest.raises(InvalidFrameError):
+        with pytest.raises(InvalidDataError):
             decode_frame(WindowUpdateFrame(0).serialize())
 
-        with pytest.raises(InvalidFrameError):
+        with pytest.raises(InvalidDataError):
             decode_frame(WindowUpdateFrame(2**31).serialize())
 
 
@@ -829,14 +829,14 @@ def test_short_altsvc_frame_errors(self):
             decode_frame(self.payload_with_origin[:10])
 
     def test_altsvc_with_unicode_origin_fails(self):
-        with pytest.raises(InvalidFrameError):
+        with pytest.raises(InvalidDataError):
             AltSvcFrame(
                 stream_id=0, origin=u'hello', field=b'h2=":8000"; ma=60'
 
             )
 
     def test_altsvc_with_unicode_field_fails(self):
-        with pytest.raises(InvalidFrameError):
+        with pytest.raises(InvalidDataError):
             AltSvcFrame(
                 stream_id=0, origin=b'hello', field=u'h2=":8000"; ma=60'
             )