index.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#hide\n",
    "from fastcgi import *"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# fastcgi\n",
    "\n",
    "> FastCGI and HTTP handlers for Python's `socketserver` classes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[FastCGI](http://www.mit.edu/~yandros/doc/specs/fcgi-spec.html) is a way for front-end servers to talk to back-end workers in a (somewhat) efficient and (somewhat) simple way. Although it's been around since 1996, it is not very widely appreciated, except in the PHP community, where it is very commonly used.\n",
    "\n",
    "It can be a great approach for hosting Python scripts, avoiding the overhead of creating a new Python process for every request (as standard CGI would otherwise require) and without requiring large dependencies, complex C projects, or fiddly deployments. `fastcgi` has no dependencies other than [fastcore](https://fastcore.fast.ai/).\n",
    "\n",
    "There's no new frameworks or concepts to learn. Just call `send` to send anything you like back to the client, read the parameters from `params`, and the input from the client from `stdin`.\n",
    "\n",
    "`fastcgi` requires a front-end web server. If you don't already have one set up, we recommend [Caddy](https://caddyserver.com/). To forward all requests to `example.com` to a `fastcgi` server listening on port 1234 create a file called `Caddyfile` with the following contents, and then `caddy run`:\n",
    "\n",
    "    example.com\n",
    "    reverse_proxy localhost:1234 { transport fastcgi }\n",
    "\n",
    "This library also provides an HTTP handler that can be used in an identical way, except remove `{ transport fastcgi }` from the above `Caddyfile` example. Python's standard library already includes an HTTP handler (in `http.server`), however the documentation warns that that module should not be used in production code. The HTTP handler provided here is trimmed down to a minimal implementation (just 40 lines of code) so that it can easily be studied and extended. It uses the same basic API as Python's other `socketserver` classes (and the same as `FcgiHandler` here) so there's fewer new concepts to understand."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Install"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`pip install fastcgi` or `conda install -c fastai fastcgi`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## How to use"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "See the full docs pages for each class for details. Quick overviews of each approach are shown below."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### fastcgi decorator"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using the `fastcgi` decorator you can use CGI scripts with minimal changes. Just add the decorator above a function used for CGI, and it converts that script automatically into a FastCGI server, e.g if you save this as `server.py`:\n",
    "\n",
    "```python\n",
    "@fastcgi()\n",
    "def hello():\n",
    "    query = os.environ[\"QUERY_STRING\"]\n",
    "    content = sys.stdin.read()\n",
    "    sys.stdout.write(f\"Content-type: text/html\\r\\n\\r\\n<html>{content} ; \")\n",
    "    sys.stdout.write(f\"{query}</html>\\r\\n\")\n",
    "```\n",
    "\n",
    "...then if you run `python server.py` it will make a unix socket available as `fcgi.sock` in the current directory."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### FcgiHandler"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`FcgiHandler` is used in much the same way as Python's [BaseRequestHandler](https://docs.python.org/3/library/socketserver.html#request-handler-objects). Here's an example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class TestHandler(FcgiHandler):\n",
    "    def handle(self):\n",
    "        print('query:', self.environ['QUERY_STRING'])\n",
    "        print('content type:', self.environ['HTTP_CONTENT_TYPE'])\n",
    "        print('stdin:', self['stdin'].read())\n",
    "        self['stdout'].write(b\"Content-type: text/html\\r\\n\\r\\n<html>foobar</html>\\r\\n\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can run this using any of Python's `socketserver` classes, e.g to listen on localhost port 1234:\n",
    "\n",
    "```python\n",
    "with TCPServer(('localhost',1234), TestHandler) as srv:\n",
    "    srv.handle_request()\n",
    "```\n",
    "\n",
    "See the API docs for `FcgiHandler` for an end-to-end example.\n",
    "\n",
    "You can also create a forking or threading server by using Python's [mixins or predefined classes](https://docs.python.org/3/library/socketserver.html#socketserver.ThreadingMixIn).\n",
    "\n",
    "In your `handle` method, you can use the `stdin`, `stdout`, and `stderr` attributes, which each contain a `BytesIO` stream."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### MinimalHTTPHandler"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`fastcgi` also comes with the `MinimalHTTPHandler` class, which provides very similar functionality to `FcgiHandler`, but using the `HTTP` protocol instead of the `FastCGI` protocol. Here's an example:\n",
    "\n",
    "```python\n",
    "class _TestHandler(MinimalHTTPHandler):\n",
    "    def handle(self):\n",
    "        print(f'Command/path/version: {self.command} {self.path} {self.request_version}')\n",
    "        print(self.headers)\n",
    "        self.send_response(200)\n",
    "        self.send_header(\"Content-Type\", \"text/plain\")\n",
    "        self.send_header('Content-Length', '2')\n",
    "        self.end_headers()\n",
    "        self.wfile.write(b'ok')\n",
    "```\n",
    "\n",
    "You can run it with a `socketserver` server in the same way shown above for `FcgiHandler`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}