httpcoding

nimony/lib/std/http/httpcoding.nim

• const AcceptCodings: string

  What a client built on this module can decode, ready for Accept-Encoding.

• type ContentCoding = enum
    ceIdentity = (0, "ceIdentity")
    ceGzip = (1, "ceGzip")
    ceDeflate = (2, "ceDeflate")
    ceUnknown = (3, "ceUnknown")

• func dollar`.ContentCoding(e: ContentCoding): string
• proc chooseCoding(acceptEncoding: openArray[char]): ContentCoding

  The coding to answer with, given a request's Accept-Encoding value: ceGzip or ceDeflate when the client accepts one with a non-zero qvalue (gzip on a tie), else ceIdentity.

  * covers whatever is not named, and an explicit q=0 takes a coding off the table even when * would have allowed it — gzip;q=0, * means "anything but gzip", and that is exactly the client that has a reason.

• proc chooseCoding(m: HttpMsg): ContentCoding

  The coding a response to request m may use. No Accept-Encoding is answered with identity: RFC 9110 lets a server assume anything then, and no server does, because the clients that omit it are the ones that cannot decode.

• proc isCompressible(contentType: openArray[char]): bool

  Whether a body of this media type is worth compressing: text and the structured text formats, not images, archives or video, which are compressed already and only grow.

  text/event-stream is the exception among the text types. Its events have to reach the client one at a time, and a coding buffers.

• proc codingOf(m: HttpMsg): ContentCoding

  The coding m's body is in, from its Content-Encoding. The parser already resolved the common values to tags, so this is usually an integer compare.

• proc codingTag(c: ContentCoding): HttpTag

  The Content-Encoding value for c.

• proc encodeFormat(c: ContentCoding): Format

  The container to write for c. deflate is zlib: RFC 9110 says so, and raw DEFLATE is what the servers that got it wrong sent, not what anyone should send now.

• type ContentDecoder = object
    coding: ContentCoding
    dec: Decoder
    limit: int64
    rawLimit: int64
    raw: int64

• proc initContentDecoder(coding: ContentCoding; limit: int64): ContentDecoder

  UnimplementedOperation is the caller's to raise for ceUnknown before getting here: it is a 415 on a server and a failure on a client, and only the caller knows which it is.

  The encoded side is capped too, a little above limit. Without that, empty stored blocks — five bytes each, producing nothing — would let a chunked body run forever under a decoded limit it never reaches.

• proc add(cd: var ContentDecoder; piece: openArray[char]; dest: var string)

  Decode piece, appending to dest. ContentTooLong past either limit, SyntaxError for a coding that is corrupt.

• proc finish(cd: ContentDecoder)

  The body has ended. SyntaxError when the coding had not: a compressed body cut short decodes to a prefix that looks like a whole, and the trailer check is the only thing that tells them apart.

• proc readContent(c: var HttpConn; m: HttpMsg; limit: int64; dl: Deadline): string

  The whole body of m — just read by readResponse or readRequest — with its framing and its content coding both undone.

  A body with neither Content-Length nor chunking is read to the end of the connection, which for a response is what that means. Not for a response to HEAD, or a 1xx, 204 or 304: those have no body whatever the headers say, and only the caller knows the request was a HEAD.

  UnimplementedOperation for a coding this cannot undo, ContentTooLong past limit decoded bytes, SyntaxError for a coding that is corrupt or cut short, plus whatever reading raises.