brubeck Documentation Release a James Dennis September 27, 2017 Contents 1 Installing The Environment 3 1.1 ZeroMQ.................................................3 1.2 Mongrel2.................................................3 1.3 Virtualenv & Virtualenvwrapper.....................................4 1.4 Python Packages & Brubeck.......................................4 2 A Demo 7 2.1 Mongrel2 Configuration.........................................7 3 Learn By Example 9 3.1 Abstract..................................................9 3.2 Kicking Mongrel2’s Tires........................................9 4 The Demos 11 5 Classes And Functions 13 6 URL Design And Handling 15 7 Template Rendering 17 8 Authentication 19 8.1 Auth Over POST............................................. 19 8.2 Authenticated Website.......................................... 20 9 Deploying 23 9.1 Mongrel2................................................. 23 9.2 WSGI................................................... 23 9.3 Deployment Environments........................................ 24 10 Copyright 2012 J2 Labs LLC. All rights reserved. 27 11 Features 29 11.1 Message Handlers............................................ 29 11.2 Templates................................................. 31 11.3 Data Modeling.............................................. 33 11.4 AutoAPI................................................. 36 11.5 Examples................................................. 38 i 11.6 File Uploading.............................................. 39 11.7 QuerySets................................................ 40 12 Architecture 41 12.1 Concurrency............................................... 41 12.2 ZeroMQ................................................. 43 12.3 Brubeck and ZMQ............................................ 44 12.4 Dependencies............................................... 45 13 API 47 13.1 brubeck Package............................................. 47 14 Summary 49 14.1 What Is Brubeck?............................................ 49 14.2 Example: Hello World.......................................... 49 14.3 Complete Examples........................................... 50 14.4 Contact Us................................................ 50 Python Module Index 53 ii brubeck Documentation, Release a Contents 1 brubeck Documentation, Release a 2 Contents CHAPTER 1 Installing The Environment First, we have to install a few things. Brubeck depends on Mongrel2, ZeroMQ and a few python packages. All three packages live in github, so we’ll clone the repos to our Desktop. $ cd ~/Desktop/ $ git clone https://github.com/j2labs/brubeck.git $ git clone https://github.com/zedshaw/mongrel2.git $ wget http://download.zeromq.org/historic/zeromq-2.1.9.tar.gz $ tar zxf zeromq-2.1.9.tar.gz ZeroMQ ZeroMQ, from a Python perspective, is actually two pieces: libzmq and pyzmq. libzmq must be installed by hand like you see below. $ cd ~/Desktop/zeromq-2.1.9 $ ./autogen.sh $ ./configure ## for mac ports use: ./configure --prefix=/opt/local $ make $ sudo make install Mongrel2 Mongrel2 is also painless to setup. $ cd ~/Desktop/mongrel2 $ make ## for mac ports use: make macports ## Mongrel 2 requires sqlite3 and dev libraries of sqlite3 $ sudo apt-get install sqlite3 3 brubeck Documentation, Release a $ sudo apt-get install libsqlite3-dev $ sudo make install There are a few compile options available at the bottom of Mongrel2’s Makefile. Take a look if the code above doesn’t compile successfully. Virtualenv & Virtualenvwrapper Brubeck works great with virtualenv. I highly recommend using it. Virtualenv is a way to construct isolated python environments. Very handy for managing multiple environments in a single machine. Install both virtualenv and virtualenvwrapper with pip. pip install virtualenv virtualenvwrapper Then, we must configure our shell to know where to store our virtualenv’s. While we’re there, we’ll source the virtualenvwrapper shell script. Open your .profile or .bashrc and add the following two lines. export WORKON_HOME="~/.virtualenvs" source/usr/local/bin/virtualenvwrapper.sh By sourcing virtualenvwrapper, you get a simple interface for creating, managing and removing virutalenv environ- ments. $ mkvirtualenv <env_name> # Creates a virtual environment $ deactivate # Turn off a virtual environment $ workon <env_name> # Turn on a virtual environment For more information, see my quick & dirty howto. • Quick & Dirty Virtualenv & Virtualenvwrapper Python Packages & Brubeck If you have pip installed, you can install everything with the requirements file. $ cd ~/Desktop/brubeck $ pip install -I -r ./envs/brubeck.reqs We now choose either eventlet or gevent and install the relevent requirements file in the same directory. To install eventlet support: $ pip install -I -r ./envs/eventlet.reqs To install gevent support: $ pip install -I -r ./envs/gevent.reqs Note that gevent requires libevent, which should be available on the package-manager of your choice. 4 Chapter 1. Installing The Environment brubeck Documentation, Release a Brubeck Itself As the last step, install Brubeck. $ cd ~/Desktop/brubeck $ python setup.py install 1.4. Python Packages & Brubeck 5 brubeck Documentation, Release a 6 Chapter 1. Installing The Environment CHAPTER 2 A Demo Assuming the environment installation went well we can now turn on Brubeck. First, we setup the Mongrel2 config. $ cd ~/Desktop/brubeck/demos $ m2sh load -config mongrel2.conf -db the.db $ m2sh start -db the.db -host localhost Now we’ll turn on a Brubeck instance. $ cd ~/Desktop/brubeck/demos $ ./demo_minimal.py If you see Brubeck v0.x.x online ]------------ we can try loading a URL in a browser. Now try a web request. Mongrel2 Configuration Mongrel2 is a separate process from Brubeck, so it is configured separately. This is what the Mongrel2 configuration looks like for the demo project. brubeck_handler= Handler ( send_spec='ipc://127.0.0.1:9999', send_ident='34f9ceee-cd52-4b7f-b197-88bf2f0ec378', recv_spec='ipc://127.0.0.1:9998', recv_ident='') brubeck_host= Host ( name="localhost", routes={'/': brubeck_handler}) brubeck_serv= Server ( 7 brubeck Documentation, Release a uuid="f400bf85-4538-4f7a-8908-67e313d515c2", access_log="/log/mongrel2.access.log", error_log="/log/mongrel2.error.log", chroot="./", default_host="localhost", name="brubeck test", pid_file="/run/mongrel2.pid", port=6767, hosts= [brubeck_host]) settings= {"zeromq.threads": 1} servers= [brubeck_serv] In short: any requests for http://localhost:6767/ should be sent to the Brubeck handler. Don’t forget that our Brubeck handler is only configured to answer http://localhost:6767/brubeck for now. You could add another route once you’re comfortable building MessageHandler‘s The web server answers requests on port 6767. It logs to the ./log directory. It also writes a pidfile in the ./run directory. 8 Chapter 2. A Demo CHAPTER 3 Learn By Example Each demo attempts to explain some of the nuances of Brubeck. Each example should be run from inside the demos directory after Brubeck has been installed. This document assumes you have already read the README. If you have not, please read that and come back after. Abstract We begin by building some knowledge of Mongrel2’s internals using sqlite3 and m2reader.py. Then there are four sets of demos. The first set contains the two demos from the README that build request handlers using classes or functions. Then we discuss how URL’s are mapped to handlers. Template rendering is then shown for Jinja2, Tornado templates and Mako. This doc is then finished with an explanation of authentication over two final demos. Kicking Mongrel2’s Tires Each of these tests can be run underneath the same Mongrel2 instance. You can bring the handlers down and back up without taking Mongrel2 down. First, we parse the config file into a sqlite database. Configuring the database this way makes the experience of editing configs as easy as editing text, but the database is stored in a programmatically friendly way too via SQLite. There is no need to edit the config so we can just load the config into a database using m2sh load. $ m2sh load -config mongrel2.conf -db the.db Now we have a sqlite database representing our config. If you have sqlite installed, open the database and take a look. You can start by typing .tables at the prompt to get a table list. 9 brubeck Documentation, Release a $ sqlite3 the.db sqlite> .tables directory host mimetype route setting handler log proxy server statistic sqlite> select * from route; 1|/|0|1|1|handler 2|/media/|0|1|1|dir We can then turn Mongrel2 on with m2sh start. $ m2sh start -db the.db -host localhost ... # lots of output [INFO] (src/handler.c:285) Binding handler PUSH socket ipc://127.0.0.1:9999 with ,!identity: 34f9ceee-cd52-4b7f-b197-88bf2f0ec378 [INFO] (src/handler.c:311) Binding listener SUB socket ipc://127.0.0.1:9998 ,!subscribed to: [INFO] (src/control.c:401) Setting up control socket in at ipc://run/control OK. Mongrel2 is now listening on port 6767 and sending messages down a ZeroMQ push socket, ipc://127.0.0.1:9999 m2reader.py Wanna see what Mongrel2 is actually saying? Turn on m2reader.py. It won’t respond with a proper web request, but you can see the entire JSON message passed to Brubeck from Mongrel2. $ ./m2reader.py 34f9ceee-cd52-4b7f-b197-88bf2f0ec378 0 / 571:{"PATH":"/","x-forwarded-for":"127.0.0.1 ,!","accept-language":"en-US,en;q=0.8","accept-encoding":"gzip,deflate,sdch", ,!"connection":"keep-alive","accept-charset":"ISO-8859-1,utf-8;q=0.7,*;q=0.3","accept ,!":"text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8","user-agent":