# asynchttpserver

Dark Mode

- Manual
- Standard library
- Index

Search:
Group by:

This module implements a high performance asynchronous HTTP server.

This HTTP server has not been designed to be used in production, but for testing applications locally. Because of this, when deploying your application you should use a reverse proxy (for example nginx) instead of allowing users to connect directly to this server.

# Basic usage

This example will create an HTTP server on port 8080. The server will respond to all requests with a `200 OK` response code and "Hello World" as the response body.

    import asynchttpserver, asyncdispatch

    var server = newAsyncHttpServer()
    proc cb(req: Request) {.async.} =
      await req.respond(Http200, "Hello World")

    waitFor server.serve(Port(8080), cb)

# Imports

asyncnet, asyncdispatch, parseutils, uri, strutils, httpcore

# Types

    Request = object
      client*: AsyncSocket
      reqMethod*: HttpMethod
      headers*: HttpHeaders
      protocol*: tuple[orig: string, major, minor: int]
      url*: Uri
      hostname*: string          ## The hostname of the client that made the request.
      body*: string

  Source Edit

    AsyncHttpServer = ref object
      socket: AsyncSocket
      reuseAddr: bool
      reusePort: bool
      maxBody: int               ## The maximum content-length that will be read for the body.

  Source Edit

# Procs

    proc newAsyncHttpServer(reuseAddr = true; reusePort = false; maxBody = 8388608): AsyncHttpServer {...}{.
        raises: [], tags: [].}

  Creates a new `AsyncHttpServer` instance. Source Edit

    proc sendHeaders(req: Request; headers: HttpHeaders): Future[void] {...}{.
        raises: [Exception, FutureError], tags: [RootEffect].}

  Sends the specified headers to the requesting client. Source Edit

    proc respond(req: Request; code: HttpCode; content: string;
                 headers: HttpHeaders = nil): Future[void] {...}{.
        raises: [Exception, FutureError], tags: [RootEffect].}

  Responds to the request with the specified `HttpCode`, headers and content.

  This procedure will not close the client socket.

  Example:

      import json
      proc handler(req: Request) {.async.} =
        if req.url.path == "/hello-world":
          let msg = %* {"message": "Hello World"}
          let headers = newHttpHeaders([("Content-Type","application/json")])
          await req.respond(Http200, $msg, headers)
        else:
          await req.respond(Http404, "Not Found")

  Source Edit

    proc serve(server: AsyncHttpServer; port: Port;
               callback: proc (request: Request): Future[void] {...}{.closure, gcsafe.};
               address = ""): owned(Future[void]) {...}{.
        raises: [Exception, FutureError],
        tags: [RootEffect, WriteIOEffect, ReadIOEffect].}

  Starts the process of listening for incoming HTTP connections on the specified address and port.

  When a request is made by a client the specified callback will be called.

  Source Edit

    proc close(server: AsyncHttpServer) {...}{.raises: [Exception, SslError, OSError],
                                          tags: [RootEffect].}

  Terminates the async http server instance. Source Edit

# Exports

Http417, Http503, Http431, ==, contains, Http304, Http406, ==, $, clear, Http408, $, Http411, is3xx, Http418, Http206, HttpPost, HttpMethod, Http101, httpNewLine, Http505, Http413, newHttpHeaders, HttpVer11, HttpTrace, Http200, []=, Http414, add, Http401, Http205, ==, Http407, Http500, Http404, Http416, Http302, HttpHeaders, Http300, Http428, Http410, is2xx, Http202, Http502, headerLimit, HttpHeaderValues, contains, newHttpHeaders, $, [], HttpHead, Http305, Http451, Http409, Http504, Http426, HttpConnect, hasKey, del, HttpPut, pairs, Http429, HttpVersion, HttpVer10, []=, Http421, HttpOptions, Http307, Http301, HttpPatch, is4xx, Http203, getOrDefault, Http100, Http501, HttpDelete, len, Http400, Http403, HttpGet, is5xx, Http415, toString, Http412, Http405, Http303, Http204, Http201, HttpCode, httpcore, Http422, []