Package org.microproxy.quic

Class QuicFraming

java.lang.Object
org.microproxy.quic.QuicFraming
public final class QuicFraming extends Object
Which MessageFramer cuts the streams of an intercepted QUIC connection into messages, for a QuicInterceptor that overrides QuicInterceptor.streamMessage(org.microproxy.quic.QuicMessage, org.microproxy.quic.QuicStreamContext); the limit on a message's size; and the error code a stream is reset with when a message is too large or malformed. Configure it with HttpProxyServerBootstrap.withQuicFraming(org.microproxy.quic.QuicFraming).

Rules map a key to a framer's name. A key is an ALPN protocol (doq), a host name (dns.example.com, matched against the server's host and the SNI, ignoring case; *.example.com also matches the names below it), or * for any connection. A host rule wins over an ALPN rule, which wins over *. The framers' names: u16, u32, varint, lf and crlf (see MessageFramer), none for no framing, and names given with withFramer(java.lang.String, org.microproxy.quic.MessageFramer) (a script's framer is script). 


 QuicFraming framing = QuicFraming.parse("myproto=varint,dns.example.com=u16,*=none")   // --quic-framing
         .withRule("chat", MessageFramer.lines())
         .withMaxMessageSize(64 * 1024);                                               // --quic-max-message-size

defaults() frames DNS over QUIC (doq) with u16, as RFC 9250 says; every other connection is unframed. Framing applies only to an interceptor that overrides streamMessage: other interceptors see each read through QuicInterceptor.streamData(org.microproxy.quic.QuicStreamMessage, org.microproxy.quic.QuicStreamContext), and nothing is kept. Instances are immutable; the with methods return changed copies.

  • Field Details

    • DEFAULT_MAX_MESSAGE_SIZE

      public static final int DEFAULT_MAX_MESSAGE_SIZE
      The default limit on a message's size, its prefix or delimiter included: 1 MiB.
      See Also:

    • DEFAULT_ERROR_CODE

      public static final long DEFAULT_ERROR_CODE
      The default application error code of the resets for a message that is too large or malformed: 0x2, DOQ_PROTOCOL_ERROR in DNS over QUIC (RFC 9250 section 8.4).
      See Also:

    • NONE

      public static final String NONE
      The name of no framing.
      See Also:

  • Method Details

    • defaults

      public static QuicFraming defaults()
      Returns the default framing: doq=u16, with the default limit and error code.
      Returns:
      the default framing: doq=u16, with the default limit and error code

    • none

      public static QuicFraming none()
      Returns no rules at all: every connection unframed, DNS over QUIC included.
      Returns:
      no rules at all: every connection unframed, DNS over QUIC included

    • parse

      public static QuicFraming parse(String spec)
      The defaults with the rules of spec added, as --quic-framing gives them.
      Parameters:
      spec - comma-separated key=framer rules, such as doq=u16,myproto=varint,*=none
      Returns:
      the framing
      Throws:
      IllegalArgumentException - if a rule is not key=framer

    • withRules

      public QuicFraming withRules(String spec)
      These rules with those of spec added; a rule for a key that has one replaces it.
      Parameters:
      spec - comma-separated key=framer rules
      Returns:
      the copy
      Throws:
      IllegalArgumentException - if a rule is not key=framer

    • withRule

      public QuicFraming withRule(String key, String framer)
      These rules with one more: key framed by the framer named framer.
      Parameters:
      key - an ALPN protocol, a host name (*.example.com for the names below it) or *
      framer - a framer's name, or "none"
      Returns:
      the copy

    • withRule

      public QuicFraming withRule(String key, MessageFramer framer)
      These rules with one more: key framed by framer, which is given the name key among the framers.
      Parameters:
      key - an ALPN protocol, a host name or *
      framer - the framer
      Returns:
      the copy

    • withFramer

      public QuicFraming withFramer(String name, MessageFramer framer)
      These rules with a framer that rules can name, replacing one of the same name.
      Parameters:
      name - the name (not a built-in framer's)
      framer - the framer
      Returns:
      the copy
      Throws:
      IllegalArgumentException - if name is a built-in framer's or "none"

    • withMaxMessageSize

      public QuicFraming withMaxMessageSize(int maxMessageSize)
      These rules with another limit on a message's size.
      Parameters:
      maxMessageSize - the most bytes a message may have, its prefix or delimiter included
      Returns:
      the copy
      Throws:
      IllegalArgumentException - if the limit is not positive

    • withErrorCode

      public QuicFraming withErrorCode(long errorCode)
      These rules with another error code for the resets of a stream whose message is too large or malformed.
      Parameters:
      errorCode - the application error code, below 262
      Returns:
      the copy
      Throws:
      IllegalArgumentException - if the code is negative or too large for QUIC

    • rules

      public Map<String,String> rules()
      Returns the rules, key to framer name, in lower case and in the order given.
      Returns:
      the rules, key to framer name, in lower case and in the order given

    • maxMessageSize

      public int maxMessageSize()
      Returns the most bytes a message may have, its prefix or delimiter included.
      Returns:
      the most bytes a message may have, its prefix or delimiter included

    • errorCode

      public long errorCode()
      Returns the application error code of the resets for a message that is too large or malformed.
      Returns:
      the application error code of the resets for a message that is too large or malformed

    • framerFor

      public MessageFramer framerFor(String alpn, String host, String sni)
      The framer for a connection: that of the first host rule matching host or sni, else that of the alpn rule, else that of *.
      Parameters:
      alpn - the negotiated ALPN protocol, or null
      host - the server's host name or address, or null
      sni - the SNI, or null
      Returns:
      the framer, or null for none
      Throws:
      IllegalStateException - if the rule names a framer there is none of

    • framerFor

      public MessageFramer framerFor(QuicContext connection)
      The framer for an intercepted connection, by its ALPN, host and SNI.
      Parameters:
      connection - the connection
      Returns:
      the framer, or null for none
      Throws:
      IllegalStateException - if the rule names a framer there is none of

    • validate

      public void validate()
      Checks that every rule names a framer there is.
      Throws:
      IllegalArgumentException - naming the first rule that does not

    • toString

      public String toString()
      Overrides:
      toString in class Object