httpmsg

nimony/lib/std/http/httpmsg.nim

• type HttpTag = enum
    tReq = (0, "tReq")
    tRes = (1, "tRes")
    tXhdr = (2, "tXhdr")
    tV10 = (3, "tV10")
    tV11 = (4, "tV11")
    tV20 = (5, "tV20")
    mGet = (6, "mGet")
    mHead = (7, "mHead")
    mPost = (8, "mPost")
    mPut = (9, "mPut")
    mDelete = (10, "mDelete")
    mConnect = (11, "mConnect")
    mOptions = (12, "mOptions")
    mTrace = (13, "mTrace")
    mPatch = (14, "mPatch")
    hAccept = (15, "hAccept")
    hAcceptCharset = (16, "hAcceptCharset")
    hAcceptEncoding = (17, "hAcceptEncoding")
    hAcceptLanguage = (18, "hAcceptLanguage")
    hAcceptRanges = (19, "hAcceptRanges")
    hAge = (20, "hAge")
    hAllow = (21, "hAllow")
    hAuthorization = (22, "hAuthorization")
    hCacheControl = (23, "hCacheControl")
    hConnection = (24, "hConnection")
    hContentDisposition = (25, "hContentDisposition")
    hContentEncoding = (26, "hContentEncoding")
    hContentLanguage = (27, "hContentLanguage")
    hContentLength = (28, "hContentLength")
    hContentLocation = (29, "hContentLocation")
    hContentRange = (30, "hContentRange")
    hContentType = (31, "hContentType")
    hCookie = (32, "hCookie")
    hDate = (33, "hDate")
    hEtag = (34, "hEtag")
    hExpect = (35, "hExpect")
    hExpires = (36, "hExpires")
    hForwarded = (37, "hForwarded")
    hFrom = (38, "hFrom")
    hHost = (39, "hHost")
    hIfMatch = (40, "hIfMatch")
    hIfModifiedSince = (41, "hIfModifiedSince")
    hIfNoneMatch = (42, "hIfNoneMatch")
    hIfRange = (43, "hIfRange")
    hIfUnmodifiedSince = (44, "hIfUnmodifiedSince")
    hLastModified = (45, "hLastModified")
    hLocation = (46, "hLocation")
    hMaxForwards = (47, "hMaxForwards")
    hOrigin = (48, "hOrigin")
    hPragma = (49, "hPragma")
    hProxyAuthenticate = (50, "hProxyAuthenticate")
    hProxyAuthorization = (51, "hProxyAuthorization")
    hRange = (52, "hRange")
    hReferer = (53, "hReferer")
    hRetryAfter = (54, "hRetryAfter")
    hServer = (55, "hServer")
    hSetCookie = (56, "hSetCookie")
    hTe = (57, "hTe")
    hTrailer = (58, "hTrailer")
    hTransferEncoding = (59, "hTransferEncoding")
    hUpgrade = (60, "hUpgrade")
    hUserAgent = (61, "hUserAgent")
    hVary = (62, "hVary")
    hVia = (63, "hVia")
    hWarning = (64, "hWarning")
    hWwwAuthenticate = (65, "hWwwAuthenticate")
    hXForwardedFor = (66, "hXForwardedFor")
    hXForwardedProto = (67, "hXForwardedProto")
    hXRequestId = (68, "hXRequestId")
    vKeepAlive = (69, "vKeepAlive")
    vClose = (70, "vClose")
    vChunked = (71, "vChunked")
    vGzip = (72, "vGzip")
    vDeflate = (73, "vDeflate")
    vIdentity = (74, "vIdentity")
    vTrailers = (75, "vTrailers")
    vNoCache = (76, "vNoCache")
    vNoStore = (77, "vNoStore")

• func dollar`.HttpTag(e: HttpTag): string
• const vUpgrade: HttpTag

  Connection: upgrade. The same spelling names a header and one of Connection's values, and a tag pool maps spellings to ids — so they are one tag, and the position in the tree says which role it is in.

• const MethodLow: HttpTag
• const MethodHigh: HttpTag
• const HeaderLow: HttpTag
• const HeaderHigh: HttpTag
• const ValueLow: HttpTag
• const ValueHigh: HttpTag
• const MaxHttpTags: int64

  One-token tag ids. See HttpTags on why we stop here rather than spending a second token.

• const MaxTagNameLen: int64

  Longest spelling lookupHeader will even consider. Every built-in tag is far shorter, so this only ever rejects something that was going to miss anyway — cheaply, and without touching the pool.

• type HttpTags = ref HttpTags.Obj not nil

• type HttpTags.Obj = object
    pool: ref TagPool.Obj
    byLen: seq
    lenStart: array[0..65, int32]

• proc newHttpTags(): ref HttpTags.Obj not nil

  A fresh tag space, seeded with the built-in vocabulary. An application makes ONE during init and threads it: into every HttpMsg it builds, into every HttpConn it serves, and into registerHeader for the headers it indexes on. An id only means anything against the space it came from, so passing it is what makes "the same id everywhere" a property you can see in the signatures rather than one the process has to promise.

• template tag(e: HttpTag): TagId

  The pool id of a built-in tag. Ids are ord + 1 by construction, so this is arithmetic, not a lookup.

• proc isMethod(t: TagId): bool
• proc isKnownHeader(t: TagId): bool
• proc name(tags: ref HttpTags.Obj not nil; t: TagId): string

  The wire spelling of a registered tag; "" for an id nobody registered.

• template spelling(tags: ref HttpTags.Obj not nil; t: TagId): lent string

  The wire spelling, borrowed rather than copied — a template so it inlines to the table access. This is what a serializer wants; name copies.

• proc registerHeader(tags: ref HttpTags.Obj not nil; name: string): TagId

  Register a header the application indexes on, so it gets the same integer-compare treatment as hHost. Call during init, before the first connection: a tag space is monotonic, so a name added later is one every message parsed against it so far reported as (xhdr …).

  Returns TagId(0) when the tag space is full — a startup error, and the only reason this can fail.

  Idempotent: a name already registered comes back with the pool untouched, so several independent components (or several tests sharing one tag space) can each ask for the headers they need without having to agree on who goes first.

• proc lookupHeader(tags: ref HttpTags.Obj not nil; name: openArray): TagId

  Wire bytes to a TagId, folding ASCII case as HTTP requires. Answers TagId(0) for a name nobody registered — those become (xhdr …).

  This never interns, and it never allocates. It is the one lookup the parser is allowed to perform on attacker-controlled bytes.

• proc lookupValue(tags: ref HttpTags.Obj not nil; name: openArray): TagId

  Like lookupHeader, but answers only for spellings in the header-value range — so Connection: host does not come back as the host tag.

• proc lookupMethod(tags: ref HttpTags.Obj not nil; name: openArray): TagId

  Wire bytes to a method tag, case-sensitively as HTTP requires. Answers TagId(0) for anything that is not one of the nine built-in methods.

• type HttpMsg = object
    buf: TokenBuf
    tags: ref HttpTags.Obj not nil
    live: bool

• proc =wasMoved(m: var HttpMsg)

  .nodestroy: the buffer has been handed to the destination, so clearing this one must not run its destructor. Without this hook live would survive the move and a moved-from message would claim to own a buffer it no longer has — which is exactly the question the event loop asks when it decides whether to reclaim e.msg.

• proc hasBuf(m: HttpMsg): bool

  Whether this message owns a buffer. A moved-from message does not, which is how the event loop tells "the handler took it" from "it is still mine".

• proc initHttpMsg(tags: ref HttpTags.Obj not nil; cap: int64): HttpMsg

  A message with its own literal pool, sharing tags' tag space.

• proc reset(m: var HttpMsg)

  Drop the content, keeping the token buffer's allocation — which is the one that grew to fit the traffic and the reason recycling a message beats building a new one. The literal pool is replaced rather than emptied: it holds only the values too long to sit inline in a token, so it is typically small or untouched, and a fresh Pool is one allocation against the certainty that no id from the old message stays reachable.

• proc startRequest(m: var HttpMsg; meth: TagId; target: string; v: TagId)

  Begin (req (METHOD) target (version) …). Headers follow; call finish when done.

• proc startResponse(m: var HttpMsg; status: int64; v: TagId)

  Begin (res status (version) …).

• proc addHeader(m: var HttpMsg; h: TagId; value: string)

  A header whose value is a string.

• proc addHeader(m: var HttpMsg; h: TagId; value: openArray)

  As above, from a byte view — what a parser has, without cutting a slice out of its read buffer to get it.

• proc addHeader(m: var HttpMsg; h: TagId; value: int64)

  A header whose value is numeric — Content-Length and friends. Stored as an IntLit, so it is parsed once here and never re-parsed on access.

• proc addHeader(m: var HttpMsg; h: TagId; values: openArray)

  A list-valued header as one node with several children — the shape a comma-separated header is meant to take, so that reading it back does not mean splitting a string again.

• proc addHeader(m: var HttpMsg; h: TagId; value: TagId)

  A header whose value is itself drawn from a known vocabulary, e.g. (connection (keep-alive)). Checking one is then an integer compare.

• proc addHeader(m: var HttpMsg; h: HttpTag; value: string)
• proc addHeader(m: var HttpMsg; h: HttpTag; value: int64)
• proc addHeader(m: var HttpMsg; h: HttpTag; value: HttpTag)
• proc addHeader(m: var HttpMsg; h: HttpTag; values: openArray)
• proc addHeader(m: var HttpMsg; h: HttpTag; value: openArray)

  The gap in the HttpTag set: a value that is already bytes somewhere, which is how a header a server formats into a fixed buffer (Date) arrives. Without it such a caller has to spell tag(h) for this one header and not for its neighbours.

• proc addOtherHeader(m: var HttpMsg; name: string; value: string)

  A header nobody registered: (xhdr "name" "value"). The application provably does not index this by constant — if it did, it would have registered it — so this form is never on a hot path.

• proc addOtherHeader(m: var HttpMsg; name: openArray; value: openArray)

  As above, from byte views.

• proc startRequest(m: var HttpMsg; meth: TagId; target: openArray; v: TagId)

  As startRequest, with the target still in the parser's buffer.

• proc finish(m: var HttpMsg)

  Close the message node, and take the buffer's cursor owner while m is still mutable. Required before any accessor, and for two reasons now: the tree has to be closed to be walked, and every accessor below reads through readonlyCursorAt, which needs the buffer to be owned already — an ownerless cursor resolves strVal against the fallback pool rather than this message's own. finish is the one point in a message's life that is both mutable and guaranteed to run before any read.

  The owner survives until the next mutation, which prepareMutation uses to drop it again — so a recycled message re-takes it here, once.

• proc isRequest(m: HttpMsg): bool
• proc isResponse(m: HttpMsg): bool
• proc methodOf(m: HttpMsg): TagId

  The request's method tag, or TagId(0) on a response.

• proc target(m: HttpMsg): string

  The request target, or "" on a response.

• proc statusOf(m: HttpMsg): int64

  The response status, or 0 on a request.

• proc versionOf(m: HttpMsg): TagId
• proc rootCursor(m: HttpMsg): Cursor

  A cursor at the message node itself, for consumers that need the raw tree — a serializer reaching the target without copying it out, say.

• iterator headers(m: HttpMsg): TagId

  Every header in wire order. tag(tXhdr) is yielded for the unregistered ones; ask otherHeaders for their names.

  The cast is the cursor refcount, not the message: an iterator is inferred .noSideEffect and taking a reference on the buffer's owner is a write. Nothing about m changes — see readCursor.

• iterator headerNodes(m: HttpMsg): Cursor

  A cursor at each header node, so a serializer can reach the raw values without them being copied out first. sub descends into one. See headers on the cast.

• iterator otherHeaders(m: HttpMsg): tuple[string, string]

  Name/value for the headers that have no tag. See headers on the cast.

• proc contains(m: HttpMsg; h: TagId): bool

  Whether the message carries h at least once.

• proc contains(m: HttpMsg; h: HttpTag): bool
• proc countHeader(m: HttpMsg; h: TagId): int64

  How many times h appears. More than once matters for the headers that frame a message: two Content-Length lines are a request-smuggling vector, not a formatting quirk.

• proc countHeader(m: HttpMsg; h: HttpTag): int64
• proc getStr(m: HttpMsg; h: TagId): string

  The first value of h as a string, or "" when absent. A value stored as a tag ((connection (keep-alive))) reads back as its wire spelling.

• proc getStr(m: HttpMsg; h: HttpTag): string
• proc getInt(m: HttpMsg; h: TagId; default: int64): int64

  The first value of h as an integer — no re-parsing, it was stored as one. default when the header is absent or is not numeric.

• proc getInt(m: HttpMsg; h: HttpTag; default: int64): int64
• proc getTag(m: HttpMsg; h: TagId): TagId

  The first value of h when it is itself a tag, else TagId(0). This is the integer-compare path: m.getTag(hConnection) == tag(vKeepAlive).

• proc getTag(m: HttpMsg; h: HttpTag): TagId
• proc contentLength(m: HttpMsg): int64

  -1 when absent. One token read; the digits were parsed at parse time.

• proc isKeepAlive(m: HttpMsg): bool

  The check every request pays for, as an integer compare rather than a case-insensitive string compare.