🥮 mooncakes.io

    codec

    Error kinds and limits shared by the streaming codecs of gaato/codecs.mbt.

    codec
    compression
    streaming
    errors
    Download zip
    Author
    Version
    0.1.1
    License
    Apache-2.0
    Repository
    Last updated
    16 hours ago
    Downloads
    4K

    No dependencies

    #gaato/codec

    The error kinds and limits shared by the streaming codecs of codecs.mbt. A codec of any kind, a byte-stream decoder or an image decoder, raises CodecError with one of these kinds through its kind's contract, so that callers handle failures the same way whatever they decode.

    This module only defines types. A codec such as gaato/zstd brings it in, and gaato/codec_bytes re-exports its types, so a consumer of byte-stream codecs can name them with that one import instead.

    #Install

    moon add gaato/codec

    #Usage

    A CodecError carries a kind to act on and a message for people. Match on the kind, and keep a wildcard arm: ErrorKind and Resource may gain cases.

    ///|
    /// What to tell the client that sent a compressed request body.
    fn describe(error : @codec.CodecError) -> String {
      match error.kind() {
        LimitExceeded({ resource: Output, limit, .. }) =>
          "the body is over \{limit} bytes once decompressed"
        LimitExceeded(_) => "the body needs too much memory to decompress"
        Truncated => "the body ends too early"
        DictionaryRequired(_) | DictionaryMismatch =>
          "the body needs a dictionary this server does not have"
        _ => "the body is not valid"
      }
    }

    ///|
    test "describe codec errors" {
      let too_big = @codec.CodecError::CodecError(
        LimitExceeded({ resource: Output, needed: None, limit: 1024, }),
        "more than max_output bytes",
      )
      assert_eq(describe(too_big), "the body is over 1024 bytes once decompressed")
      assert_eq(
        describe(@codec.CodecError::CodecError(Truncated, "end of input")),
        "the body ends too early",
      )
    }

    #Error kinds

    • Truncated: the input ended inside a stream.
    • Corrupt: the input is not a valid stream.
    • ChecksumMismatch: a checksum, or a length the stream declares, does not match the data.
    • TrailingData: bytes follow the end of the stream.
    • LimitExceeded(limit): going on would exceed a limit. limit says which resource (Memory or Output), how much the stream needs when that is known, and how much is allowed, in bytes.
    • DictionaryRequired(id) and DictionaryMismatch: the stream needs a dictionary that was not given, or was given another one.
    • Unsupported: the stream is valid but uses something the codec does not implement.

    Each codec's README says which kinds it raises and when.

    #Links

    #License

    Apache-2.0.

    CodecError

    source
    pub(all) suberror CodecError {
      CodecError(ErrorKind, String)
    } derive(
    Debug    )

    The error every codec raises through its kind's contract: a kind to act on, and a message for people.

    CodecError::kind

    source
    fn CodecError::kind(self : CodecError) -> ErrorKind

    The kind of the error.

    CodecError::to_repr

    source

    CodecError::to_repr, the derived debug representation.

    ErrorKind

    source
    pub(all) enum ErrorKind {
      Truncated
      Corrupt
      ChecksumMismatch
      TrailingData
      LimitExceeded(Limit)
      DictionaryRequired(UInt?)
      DictionaryMismatch
      Unsupported
    } derive(Eq, 
    Debug    )

    Why a codec stopped with an error. The same kinds serve every kind of codec (byte streams, images, audio), so that callers handle a failure the same way whatever they were decoding. New kinds may be added.

    ErrorKind::equal

    source
    fn ErrorKind::equal(ErrorKind, ErrorKind) -> Bool

    ErrorKind::equal and ErrorKind::not_equal, the derived comparison.

    ErrorKind::not_equal

    source
    fn ErrorKind::not_equal(x : ErrorKind, y : ErrorKind) -> Bool

    ErrorKind::equal and ErrorKind::not_equal, the derived comparison.

    ErrorKind::to_repr

    source

    ErrorKind::to_repr, the derived debug representation.

    Limit

    source
    pub(all) struct Limit {
      resource : Resource
      needed : UInt64?
      limit : UInt64
    } derive(Eq, 
    Debug    )

    A limit a stream would exceed: what it is about, how much the stream needs when that is known, and how much is allowed. Amounts are in the resource's unit (bytes for memory and output).

    Limit::equal

    source
    fn Limit::equal(Limit, Limit) -> Bool

    Limit::equal and Limit::not_equal, the derived comparison.

    Limit::not_equal

    source
    fn Limit::not_equal(x : Limit, y : Limit) -> Bool

    Limit::equal and Limit::not_equal, the derived comparison.

    Limit::to_repr

    source

    Limit::to_repr, the derived debug representation.

    Resource

    source
    pub(all) enum Resource {
      Memory
      Output
    } derive(Eq, 
    Debug    )

    What a limit is about. New resources may be added.

    Resource::equal

    source
    fn Resource::equal(Resource, Resource) -> Bool

    Resource::equal and Resource::not_equal, the derived comparison.

    Resource::not_equal

    source
    fn Resource::not_equal(x : Resource, y : Resource) -> Bool

    Resource::equal and Resource::not_equal, the derived comparison.

    Resource::to_repr

    source

    Resource::to_repr, the derived debug representation.

    Source Files