httpserver

nimony/lib/std/httpserver.nim

const DefaultHeadMs: int64
How long a peer may take to finish sending a request head. Short on purpose and separate from the request budget: a head arriving one byte per second is the cheapest denial of service there is, and it costs the attacker nothing precisely because it never looks like a timeout of anything else.
const DefaultRequestMs: int64
The budget for one whole request-response exchange once its head has arrived, body and response included.
const DefaultIdleMs: int64
How long a kept-alive connection may sit between requests.
const DefaultMaxRequests: int64
Requests served on one connection before it is closed anyway. Not a resource limit — it is what keeps a fleet's connections rotating, so a deploy or a DNS change is picked up without waiting for peers to volunteer.
const MaxDrain: int64
The most unread request body that is worth reading and discarding to keep a connection alive. Past it the connection is closed instead: draining a body the handler did not want is work a peer chose for us, and a limit is the difference between politeness and being driven.

type HttpServer = object
  fd: int32
  tags: ref HttpTags.Obj not nil
  headMs: int64
  requestMs: int64
  idleMs: int64
  maxRequests: int64
  serverName: string
  checkTargets: bool

func dollar`.Phase(e: Phase): string

type HttpConnection = object
  conn: HttpConn
  peer: PeerAddr
  req: HttpMsg
  res: HttpMsg
  pathBuf: string
  queryBuf: string
  targetBuf: string
  phase: Phase
  keepAlive: bool
  served: int64
  bodyLeft: int64
  chunked: bool
  headMs: int64
  requestMs: int64
  idleMs: int64
  maxRequests: int64
  serverName: string
  checkTargets: bool

proc listenHttp(port: uint16; tags: ref HttpTags.Obj not nil; backlog: int64): HttpServer
Listen on port. initIoRing() must already have run.
tags is the process's one tag space (newHttpTags(), once, during init) — every message on every connection is built and parsed against it, so it is threaded in here rather than looked up per request.
proc close(s: var HttpServer)
Stop accepting. Connections already handed out are unaffected — they own their own descriptors and finish on their own chains, which is what makes a drain-then-exit shutdown just "stop calling accept".
proc accept(s: var HttpServer): HttpConnection
The next connection.
Answers a connection whose isClosed is true when the listener is gone, which is what close does to a parked accept and is therefore how an accept loop is told to stop:
while true: let c = s.accept() if c.isClosed: break submit(delay(handle(c)), -1)
Not .raises, and not because failing is impossible: a .raises proc cannot currently return a move-only object, and this one owns a descriptor. It reads better this way regardless — a listener stopping is how an accept loop is supposed to end, so it is a value and not an exception.
No deadline either: a listener with nothing connecting to it is idle, not stuck, and the thing that ends this wait is close.
proc isClosed(c: HttpConnection): bool
proc close(c: var HttpConnection)
End the connection now. Idempotent.
proc next(c: var HttpConnection): bool
Read the next request on this connection. false once there will not be one — the peer finished, the connection was closed, or something went wrong that the peer has already been told about.
Never raises. Everything that can go wrong at this level has one correct answer on the wire and this sends it: 400 for a head that does not parse or a 1.1 request with no Host, 431 for one that is too big, 408 for a peer that stopped mid-head. A handler that had to catch those would be re-deciding, per server, a question the protocol already settled.
template request(c: HttpConnection): lent HttpMsg
The parsed head, for anything the named accessors below do not cover.
template target(c: HttpConnection): lent string
Exactly what the request line said, undecoded. A proxy forwards this; an origin server wants path.
template path(c: HttpConnection): lent string
The target's path, percent-decoded and normalized, and guaranteed not to climb above /. Safe to join to a document root.
template query(c: HttpConnection): lent string
The raw query string, still encoded — uri.decodeQuery splits it, and it has to split before it decodes or a %26 becomes a separator.
proc meth(c: HttpConnection): TagId
proc isHead(c: HttpConnection): bool
proc contentLength(c: HttpConnection): int64
Declared body length, -1 for a chunked body, 0 for none.
proc hasBody(c: HttpConnection): bool
proc readBody(c: var HttpConnection; dest: var openArray): int64
The next piece of the request body: bytes copied, 0 once it has ended.
One proc for both framings, because which one the peer chose is not the handler's business — it is the difference between two correct ways of saying where a body stops, and code that asks is code that can get the answer wrong. Anything left unread is drained by the next next.
proc readBody(c: var HttpConnection; limit: int64): string
The whole body as a string, or ContentTooLong past limit.
The limit has no "unlimited" spelling on purpose: a body's length is chosen by the peer, and the version of this proc without a ceiling is one Content-Length: 999999999999 away from being the whole outage.
proc prepare(c: var HttpConnection; m: var HttpMsg; status: int64)
Start a response into m: the status line, Date, Server and Connection, so a handler adds only what is its own. respond takes it from there.
proc respond(c: var HttpConnection; m: var HttpMsg; body: openArray)
Send m — built by prepare and whatever headers the handler added — with body.
Content-Length is filled in from body unless the status forbids one, and the body itself is suppressed for HEAD and for the statuses that cannot carry one. Those two rules are why this exists rather than sendHead + sendBody: they are invisible when they are missing and they desynchronize the next response, not this one.
proc respond(c: var HttpConnection; status: int64; body: openArray; contentType: string)
The whole response in one call, which is what almost every handler wants.
proc respond(c: var HttpConnection; status: int64; body: string; contentType: string)
proc redirect(c: var HttpConnection; location: string; status: int64)
A redirect, with the Location a redirect is nothing without.
proc beginStream(c: var HttpConnection; m: var HttpMsg)
Start a chunk-framed response whose length is not known yet. Follow with write and then finish.
Chunked rather than "write until close": a response that ends by closing cannot be followed by another, so it costs the connection — and on a proxy it costs the client the ability to tell a complete response from a truncated one.
proc beginStream(c: var HttpConnection; status: int64; contentType: string)
proc write(c: var HttpConnection; data: openArray)
One piece of a streamed body. Suspends until it is on the wire, so a handler that produces faster than the peer consumes is slowed by the peer rather than by a queue that grows until something notices.
Nothing is written for a HEAD, whose response is the headers a GET would have sent and nothing after them — so a handler streams the same way for both and does not branch.
proc write(c: var HttpConnection; data: string)
proc finish(c: var HttpConnection)
End a streamed body.