# nginx-python-module **Repository Path**: moofei/nginx-python-module ## Basic Information - **Project Name**: nginx-python-module - **Description**: nginx-python-module - **Primary Language**: Python - **License**: BSD-2-Clause - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2020-04-24 - **Last Updated**: 2020-12-19 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README ******************* Nginx Python Module ******************* The module allows using Python in nginx both at configuration stage and in runtime. Compatibility ============= - nginx version >= 1.11.5 (HTTP-only version can be compiled with 1.11.2) - Python version: 2.7 - tested on recent Linux, FreeBSD and MacOS Build ===== Configuring nginx with the module:: # static module $ ./configure --add-module=/path/to/nginx-python-module # dynamic module $ ./configure --add-dynamic-module=/path/to/nginx-python-module # sync-only version (no blocking operations substitution) $ ./configure --add-module=/path/to/nginx-python-module --with-cc-opt=-DNGX_PYTHON_SYNC=1 # a specific Python installation can be used by exporting # the path to python-config prior to configuring $ export PYTHON_CONFIG=/path/to/python-config Tests ===== Like in standard nginx tests, the following environment variables are supported - ``TEST_NGINX_BINARY`` - path to the nginx binary - ``TEST_NGINX_CATLOG`` - dump error.log to stderr - ``TEST_NGINX_LEAVE`` - do not remove test directory Running tests:: # run all tests $ python t # add verbosity with -v, get help with -h $ python t -v # run an individual test $ python t/test_http_basic.py Directives ========== Global Scope ------------ - ``python`` - execute Python code in config time - ``python_include`` - include and execute Python code in config time - ``python_stack_size`` - set stack size for unblocked code, default is 32k HTTP Scope ---------- - ``python`` - execute Python code in config time - ``python_include`` - include and execute Python code in config time - ``python_set`` - create Python variable (one-line) - ``python_access`` - set up Python access handler (one-line, blocking ops) - ``python_log`` - set up Python log handler (one-line) - ``python_content`` - set up Python location content handler (one-line, blocking ops) Stream Scope ------------ - ``python`` - execute Python code in config time - ``python_include`` - include and execute Python code in config time - ``python_set`` - create Python variable (one-line) - ``python_access`` - set up Python access handler (one-line, blocking ops) - ``python_preread`` - set up Python access handler (one-line, blocking ops) - ``python_log`` - set up Python log handler (one-line) - ``python_content`` - set up Python server content handler (one-line, blocking ops) Objects and namespaces ====================== default namespaces ------------------ In HTTP default namespace the current HTTP request instance ``r`` is available. - ``hi{}`` - input headers (readonly) - ``ho{}`` - output headers (read-write) - ``var{}`` - nginx variables (readonly) - ``arg{}`` - nginx arguments (readonly) - ``ctx{}`` - request dictionary (read-write) - ``status`` - HTTP status (read-write) - ``log(msg, level)`` - write a message to nginx error log with given level - ``sendHeader()`` - send HTTP header to client - ``send(data, flags)`` - send a piece of output body, optional flags are ``SEND_LAST`` and ``SEND_FLUSH`` In Stream default namespace the current Stream session instance ``s`` is available. - ``buf`` - preread/UDP buffer (readonly) - ``sock`` - client socket, I/O is allowed only at content phase - ``var{}`` - nginx variables (readonly) - ``ctx{}`` - session dictionary (read-write) - ``log(msg, level)`` - write a message to nginx error log with given level ngx namespace ------------- In this namespace, standard constants are available Standard nginx result codes - ``OK`` - ``ERROR`` - ``AGAIN`` - ``BUSY`` - ``DONE`` - ``DECLINED`` - ``ABORT`` Log error levels - ``LOG_EMERG`` - ``LOG_ALERT`` - ``LOG_CRIT`` - ``LOG_ERR`` - ``LOG_WARN`` - ``LOG_NOTICE`` - ``LOG_INFO`` - ``LOG_DEBUG`` Send flags - ``SEND_FLUSH`` - ``SEND_LAST`` Blocking operations =================== Nginx is a non-blocking server. Using blocking operations while serving client requests, will significantly decrease its performance. The nginx-python-module provides unblocked substitutions for common blocking operations in Python, and makes these changes transparent for user. This means, you can use common blocking Python operations, while their implementations will rely on nginx non-blocking core. The list of classes and functions unblocked by the module: - ``socket.socket`` class. Unconnected (UDP) sockets, as well as Python SSL socket wrappers are not supported. - ``socket.gethostbyname()`` and other resolve functions. The ``resolver`` directive in the current location is required for these functions. - ``time.sleep()`` function. Default Python namespace ======================== For each nginx configuration a new default Python namespace is created. This namespace is shared among all global, HTTP or Stream scopes in configuration time, as well as HTTP requests and Stream sessions in runtime. The namespace can be initialized with the ``python`` and ``python_include`` directives, which operate at configuration time. Examples ======== Remote configuration -------------------- Loading the essential part of nginx configuration file from a remote server:: # nginx.conf python 'import urllib'; python 'urllib.URLopener().retrieve("http://127.0.0.1:8888/nginx.conf", "/tmp/nginx.conf")'; include /tmp/nginx.conf; Variables --------- :: # nginx.conf events {} http { python "import hashlib"; # md5($arg_foo) python_set $md5 "hashlib.md5(r.arg['foo']).hexdigest()"; server { listen 8000; location / { return 200 $md5; } } } Phase handlers -------------- Dynamic Python module is used in this example:: # nginx.conf load_module modules/ngx_python_module.so; events {} http { python_include inc.py; python_access "access(r)"; server { listen 8000; location / { python_content "content(r)"; } } } # inc.py import ngx import time import socket def access(r): r.log('access phase', ngx.LOG_INFO) r.ctx['code'] = 221 s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) s.connect(('127.0.0.1', 8001)) s.settimeout(2) s.send('foo') r.ho['X-Out'] = s.recv(10) def content(r): r.status = r.ctx['code'] r.sendHeader() r.send('1234567890'); r.send('abcdefgefg', ngx.SEND_LAST) UDP socket ---------- :: # nginx.conf events {} http { python_include inc.py; python_access "access(r)"; server { listen 8000; location / { root html; } } } # inc.py import socket # send each $request via UDP to 127.0.0.1:6000 ds = None def access(r): global ds if ds is None: ds = socket.socket(socket.AF_INET, socket.SOCK_DGRAM) ds.connect(('127.0.0.1', 6000)) ds.send(r.var['request']) HTTP request in runtime ----------------------- :: # nginx.conf events {} http { python_include inc.py; python_access "access(r)"; server { listen 8000; location / { root html; } } server { listen 8001; location / { return 200 foo; } } } # inc.py import httplib def access(r): conn = httplib.HTTPConnection("127.0.0.1", 8001) conn.request('GET', '/') resp = conn.getresponse() r.ho['x-status'] = resp.status; r.ho['x-reason'] = resp.reason; r.ho['x-body'] = resp.read() Echo server ----------- :: # nginx.conf events {} stream { python_include inc.py; server { listen 8000; python_content echo(s); } } # inc.py def echo(s): while True: b = s.sock.recv(128) if len(b) == 0: return s.sock.sendall(b)