Module scgi

This module implements helper procs for SCGI applications. Example:

import strtabs, sockets, scgi

var counter = 0
proc handleRequest(client: Socket, input: string,
                   headers: StringTableRef): bool {.procvar.} =
  inc(counter)
  client.writeStatusOkTextContent()
  client.send("Hello for the $#th time." % $counter & "\c\L")
  return false # do not stop processing

run(handleRequest)

Warning: The API of this module is unstable, and therefore is subject to change.

Warning: This module only supports the old asynchronous interface. You may wish to use the asynchttpserver instead for web applications.

Imports

sockets, strutils, os, strtabs, asyncio

Types

ScgiError = object of IOError

the exception that is raised, if a SCGI error occurs

ScgiState = object of RootObj
  server: Socket
  bufLen: int
  client*: Socket              ## the client socket to send data to
  headers*: StringTableRef     ## the parsed headers
  input*: string               ## the input buffer

SCGI state object

AsyncScgiState = ref AsyncScgiStateObj

Procs

proc raiseScgiError(msg: string) {...}{.noreturn, raises: [ScgiError], tags: [].}

raises an ScgiError exception with message msg.

proc open(s: var ScgiState; port = Port(4000); address = "127.0.0.1"; reuseAddr = false) {...}{.
    raises: [OSError, ScgiError], tags: [WriteIOEffect, ReadIOEffect].}

opens a connection.

proc close(s: var ScgiState) {...}{.raises: [], tags: [].}

closes the connection.

proc next(s: var ScgiState; timeout: int = -1): bool {...}{.
    raises: [OSError, ScgiError, OverflowError, ValueError], tags: [ReadIOEffect].}

proceed to the first/next request. Waits timeout milliseconds for a request, if timeout is -1 then this function will never time out. Returns true if a new request has been processed.

proc writeStatusOkTextContent(c: Socket; contentType = "text/html") {...}{.
    raises: [ValueError, OSError], tags: [WriteIOEffect].}

sends the following string to the socket c:

Status: 200 OK\r\LContent-Type: text/html\r\L\r\L

You should send this before sending your HTML page, for example.

proc run(handleRequest: proc (client: Socket; input: string; headers: StringTableRef): bool {...}{.
    nimcall, gcsafe.}; port = Port(4000)) {...}{.raises: [OSError, ScgiError, OverflowError,
    ValueError], tags: [WriteIOEffect, ReadIOEffect].}

encapsulates the SCGI object and main loop.

proc open(handleRequest: proc (client: AsyncSocket; input: string;
                            headers: StringTableRef) {...}{.closure, gcsafe.};
         port = Port(4000); address = "127.0.0.1"; reuseAddr = false): AsyncScgiState {...}{.
    raises: [OSError], tags: [WriteIOEffect, ReadIOEffect].}

Creates an AsyncScgiState object which serves as a SCGI server.

After the execution of handleRequest the client socket will be closed automatically unless it has already been closed.

proc register(d: Dispatcher; s: AsyncScgiState): Delegate {...}{.discardable, raises: [],
    tags: [].}

Registers s with dispatcher d.

proc close(s: AsyncScgiState) {...}{.raises: [], tags: [].}

Closes the AsyncScgiState.