This module implements an HTTP connection between a client and a server. HttpConnection provides several routines that can recognize the structure of HTTP messages transmitted over the network.

Usage

Reads a message header

import netkit/http/connection
import netkit/http/header

type
  Packet = ref object
    header: HttpHeader

var packet = new(Packet)
packet.header = HttpHeader(kind: HttpHeaderKind.Request)

var conn = newHttpConnection(socket, address)

try:
  GC_ref(packet)
  await conn.readHttpHeader(packet.header.addr)
finally:
  GC_unref(packet)

Reads a message body

let readLen = await conn.readData(buf, 1024)

Reads a message body that chunked

type
  Packet = ref object
    header: ChunkHeader

try:
  GC_ref(packet)
  await conn.readChunkHeader(packet.header.addr)
finally:
  GC_unref(packet)

if header.size == 0: # read tail
  var trailers: seq[string]
  await conn.readEnd(trailers)
else:
  var chunkLen = header.size
  var buf = newString(header.size)
  let readLen = await conn.readData(buf, header.size)
  if readLen != header.size:
    echo "Connection closed prematurely"

Sends a message

await conn.write("""
GET /iocrate/netkit HTTP/1.1
Host: iocrate.com
Content-Length: 12

foobarfoobar
""")

Imports

../misc, ../buffer/circular, header, exception, parser, chunk

Types

HttpConnection = ref object buffer: MarkableCircularBuffer parser: HttpParser socket: AsyncFD address: string closed: bool: HTTP connection object. Source Edit

Procs

proc newHttpConnection(socket: AsyncFD; address: string): HttpConnection {...}{.raises: [], tags: [].}

Creates a new HttpConnection. Source Edit

proc close(conn: HttpConnection) {...}{.inline, raises: [Exception], tags: [RootEffect].}

Closes this connection to release the resources. Source Edit

proc closed(conn: HttpConnection): bool {...}{.inline, raises: [], tags: [].}

Returns true if this connection is closed. Source Edit

proc readHttpHeader(conn: HttpConnection; header: ptr HttpHeader): Future[void] {...}{. raises: [Exception, FutureError], tags: [RootEffect].}

Reads the header of a HTTP message.

If a system error occurs during reading, an OsError will be raised. If the connection is disconnected before successful reading, a ReadAbortedError will be raised.

Source Edit

proc readChunkHeader(conn: HttpConnection; header: ptr ChunkHeader): Future[void] {...}{. raises: [Exception, FutureError], tags: [RootEffect].}

Reads the size and the extensions parts of a chunked data.

If a system error occurs during reading, an OsError will be raised. If the connection is disconnected before successful reading, a ReadAbortedError will be raised.

Source Edit

proc readChunkEnd(conn: HttpConnection; trailer: ptr seq[string]): Future[void] {...}{. raises: [Exception, FutureError], tags: [RootEffect].}

Reads the terminating chunk, trailer, and the final CRLF sequence of a chunked message.

If a system error occurs during reading, an OsError will be raised. If the connection is disconnected before successful reading, a ReadAbortedError will be raised.

Source Edit

proc readData(conn: HttpConnection; buf: pointer; size: Natural): Future[Natural] {...}{. raises: [Exception, ValueError, FutureError], tags: [RootEffect].}

Reads up to size bytes from this connection, storing the results in the buf.

The return value is the number of bytes actually read. This might be less than size that indicates the connection is at EOF.

This proc should only be used to read the message body.

If a system error occurs during reading, an OsError will be raised. If the connection is disconnected before successful reading, a ReadAbortedError will be raised.

Source Edit

proc write(conn: HttpConnection; buf: pointer; size: Natural): Future[void] {...}{.inline, raises: [Exception, ValueError, FutureError], tags: [RootEffect].}

Writes size bytes from buf to the connection.

If a system error occurs during writing, an OsError will be raised. If the connection is disconnected or other errors occurs before the write operation is successfully completed, a WriteAbortedError exception will be raised.

Source Edit

proc write(conn: HttpConnection; data: string): Future[void] {...}{.inline, raises: [Exception, ValueError, FutureError], tags: [RootEffect].}

Writes a string to the connection.

Source Edit