@kgriffs

GraphQL vs. REST

2017-08-29T21:09:00Z

Since kicking off a new project for my startup, I’ve been looking into GraphQL vs. REST.

First of all, it’s important to note that REST is a comprehensive architectural style, not a protocol. And I don’t think this is really a debate about whether to use one or the other. We’ll need both for the foreseeable future.

GraphQL really shines only as long as you are only talking about rich read-only data APIs. It really can be quite elegant. GraphQL does support mutations as well, but they are essentially just a way of tacking on RPC calls. Some devs think this is the bee’s knees, but that’s because they never really understood REST in the first place. They’ve never moved past thinking in terms of RPC or CRUD, but just using HTTP verbs instead of method names.

Case in point: we tend to write RPC-style clients for REST APIs, and then proceed to complain about REST not being a useful architectural style. It’s a self-fulfilling prophecy.

So of course they are excited to have somewhere else to go.

That’s not to say GraphQL is devoid of attractive qualities. Especially if you don’t try to use it to mutate state.

With GraphQL you can potentially reduce the number of calls to your API, conserve bandwidth, and improve client responsiveness. On the other hand, GraphQL may make it harder for the server to effectively cache responses, since different clients can query for wildly different data sets.

GitHub makes some reasonable justifications for moving to GraphQL in the latest version of their API. On the other hand, note how they appeal to their own authority as API experts to convince you that you should trust them. Maybe. Just remember, do your own homework. #youarenotgithub #youarenotfacebook

You can do some things in REST to alleviate the pain points that GitHub mentions (ala OData, API Chaining). But the GraphQL declarative style is perhaps more elegant. On the other hand, if REST clients and APIs were to make better use (or any use at all) of caching headers and HATEOS, this would be less of an issue. Performance would be improved, and REST clients would become far less brittle.

Anyway, we are still climbing the hype curve on this one. We’ll see how it turns out.

Falcon Web Framework: What's New?

2016-10-27T21:09:00Z

Earlier this year the Falcon community celebrated the web framework’s landmark 1.0 release. It takes a surprising amount of effort to make something simple and elegant, and I want to personally thank the many people who have helped us reach this point through their generous support and contributions to the project over the past few years.

When it comes to web development, there are many options to choose from within the Python community. This is actually a good problem to have, since it gives you a better chance of finding the right tool for the job. We’ve worked hard to make Falcon a useful, complementary addition to any Python web developer’s toolbox.

Some web developers choose Falcon when the job calls for high performance. For example, they may develop a performance-sensitive microservice in Falcon to complement their Django app. Falcon also works great for developing high-throughput cloud services, microservices, and app backends.

Other web developers choose Falcon when they need low-level control over the way requests are processed. They appreciate how Falcon embraces HTTP instead of paving over it. Falcon makes it easier to reason about the application and to diagnose errors, which is especially helpful in large-scale production deployments.

Finally, web developers choose Falcon due to its clean, well-documented source code. We’ve worked hard to make it easy to understand the code and to contribute improvements and add-ons. Developers have noted the educational aspects of the Falcon framework; reading its source is a great way to learn more about WSGI, HTTP, Python programming idioms, and performance tuning.

No tool is perfect, and Falcon is certainly no exception. But the framework has already come a long way and I’m excited to see what the future will bring. If you’d like to help us create that future, please consider joining the discussion and contributing a PR or two. Or, if you’ve created an add-on please consider listing it on our wiki. Thanks!

Recently we released version 1.1 of the Falcon web framework. Many thanks to everyone in the community who contributed to the 1.0 and 1.1 releases!

Here are some highlights:

New in Falcon 1.0

Please note: For a complete list of changes, including breaking changes and bug fixes, please see the changelog for version 1.0.

Code of Conduct

A code of conduct was added to solidify our community’s commitment to sustaining a welcoming, respectful culture. This was not done in response to a specific incident, but rather as a proactive measure to nip any potential problems in the bud as our community grows.

Routing Improvements

Path segments with multiple field expressions can now be defined at the same level as path segments having only a single field expression. For example, this now works:

api.add_route('/files/{name}', resource_1)
api.add_route('/files/{name}.{ext}', resource_2)

Note, however, that using different field names will still cause a conflict:

api.add_route('/files/{id}', resource_1)
api.add_route('/files/{name}/ext', resource_2)  # Raises ValueError

Falcon 1.0 also improves support for custom router implementations. API.add_route() now accepts additional parameters via *args, **kwargs. These parameters are passed through to the router’s own add_route() method. Also, falcon.routing.compile_uri_template() now supports templates that contain digits and underscores.

Request and Response Improvements

New access_route and remote_addr properties were added to the Request class for getting upstream IP addresses:

client_ip = req.access_route[0]
last_hop_ip = req.remote_addr

The Response class was given a get_header() method to give apps a way to check if a header has already been set:

request_id = resp.get_header('X-Request-ID')

Also, as of Falcon 1.0 both the Request and Response classes support range header units other than bytes:

# Per RFC 7233, the server must ignore a Range header field
# that contains a range unit that it does not understand.
use_range = (req.range_unit == 'blocks')

# Content-Range: blocks 0-63/64
resp.content_range = (0, 63, 64, 'blocks')

HTTP Error and Status Features

HTTP_422, HTTP_428, HTTP_429, HTTP_431, HTTP_451, and HTTP_511 were added to the falcon module. We also added three additional error classes, namely HTTPUnprocessableEntity, HTTPTooManyRequests, and HTTPUnavailableForLegalReasons. (The fact that some developers need that last one makes me sad, but unfortunately this is the world we live in.)

The HTTPStatus class is now available directly under the falcon module, and has been properly documented. Furthermore, support for HTTP redirections was added via a set of HTTPStatus subclasses to avoid the problem of hooks and responder methods possibly overriding the redirect. Raising an instance of one of these new redirection classes will short-circuit request processing, similar to raising an instance of HTTPError.

Also, the default 404 responder now raises an instance of HTTPError instead of manipulating the response object directly. This makes it possible to customize the response body using a custom error handler or serializer.

New Testing Framework

A new testing framework was added that should be more intuitive to use than the old one. The new testing framework performs wsgiref validation on all requests.

from falcon import testing
import myapp


class MyTestCase(testing.TestCase):
    def setUp(self):
        super(MyTestCase, self).setUp()

        # Assume the hypothetical `myapp` package has a
        # function called `create()` to initialize and
        # return a `falcon.API` instance.
        self.app = myapp.create()


class TestMyApp(MyTestCase):
    def test_get_message(self):
        doc = {u'message': u'Hello world!'}

        result = self.simulate_get('/messages/42')
        self.assertEqual(result.json, doc)

Please note that the previous testing framework is now deprecated and will be removed in a future release. Several of Falcon’s own tests have been ported to use the new framework, with the remainder to be ported in subsequent releases.

Breaking Changes in 1.0

Since 1.0 was a major release, we took the opportunity to clean up a few rough edges. Rather than list all the breaking changes here, I’ll just highlight one in particular.

In 1.0 an option was added to toggle automatic parsing of form params. Falcon will no longer automatically parse, by default, requests that have the content type “application/x-www-form-urlencoded”. This was done to avoid unintended side-effects that may arise from consuming the request stream. It also makes it more straightforward for applications to customize and extend the handling of form submissions. Applications that require this functionality must re-enable it explicitly, by setting a new request option that was added for that purpose:

app = falcon.API()
app.req_options.auto_parse_form_urlencoded = True

A full list of 1.0 breaking changes is included in the changelog.

New in Falcon 1.1

Please note: For a complete list of changes, including bug fixes, please see the changelog for version 1.1.

Request and Response Improvements

Three new properties were added to the Request class. The new bounded_stream property can be used in place of the stream property to mitigate the blocking behavior of input objects used by some WSGI servers. Also, a uri_template property was added to expose the template for the route corresponding to the path requested by the user agent.

# Load the request body directly into msgpack
resource_representation = msgpack.unpack(req.bounded_stream, encoding='utf-8')

# Log the template that was matched for this request
logger.debug(req.uri_template)

In 1.1 we also added an accept_ranges property for setting the Accept-Ranges header:

# Tell the client that they should specify ranges in terms of "blocks"
resp.accept_ranges = 'blocks'

In addition to the new properties mentioned above, a context property was implemented for the Response class to mirror the same property that is already available on the Request class. In addition, arbitrary custom attributes can now be attached to instances of both Request and Response as an alternative to adding values to the context property or implementing custom subclasses:

# Pass a "customer" resource representation to middleware via the context dict
resp.context['rr'] = customer

# ...or use a custom attribute instead of the context dict
resp.rr = customer

# Also works with Request objects
resp.set_header('X-Request-ID', req.request_id)

In other news, when working with query strings, you can now disable CSV-style parsing of query parameter values with the auto_parse_qs_csv request option. JSON-encoded query parameter values can now be retrieved and decoded in a single step via req.get_param_as_dict(). Also, req.get_param_as_bool() now recognizes “on” and “off” in support of IE’s default checkbox values.

New and Improved Error Classes

In Falcon 1.1 we added two new error classes, falcon.HTTPUriTooLong and falcon.HTTPGone. All parameters are now optional for most error classes. When no title is specified for an error, it will default to the HTTP status text (e.g., “409 Conflict”).

# The target resource is no longer available at the 
# origin server and this condition is likely to be 
# permanent.
raise falcon.HTTPGone()

# All parameters are optional now, but note that you 
# can improve the user experience by specifying some 
# details.
raise HTTPForbidden()

Better Testing

By popular demand, pytest support was added to Falcon’s testing framework:

from falcon import testing
import pytest

import myapp


@pytest.fixture(scope='module')
def client():
    # Assume the hypothetical `myapp` package has a
    # function called `create()` to initialize and
    # return a `falcon.API` instance.
    return testing.TestClient(myapp.create())


def test_get_message(client):
    doc = {u'message': u'Hello world!'}

    result = client.simulate_get('/messages/42')
    assert result.json == doc

Regardless of whether you use unittest or pytest, when simulating a request using Falcon’s testing framework, query string parameters can now be specified as a dict, as an alternative to passing a raw query string.

Also, the falcon.testing.Cookie class was added to represent a cookie returned by a simulated request; falcon.testing.Result now exposes a cookies attribute for examining returned cookies.

Middleware Processing

Falcon’s middleware processing logic was revamped to improve performance and to fix a couple of edge cases.

In addition, a req_succeeded flag is now passed to the process_request() middleware method to signal whether or not an exception was raised while processing the request:

class ExampleMiddleware(object):
    def process_response(self, req, resp, resource, req_succeeded):
        if req_succeeded:
            # ...
        else:
            # ...

Per our policy of not introducing breaking changes in point releases (not to mention never introducing undocumented breaking changes that can take you by surprise), we added shimming logic to avoid breaking existing middleware methods that do not yet accept this new parameter.

Other Goodies

A new CLI utility, falcon-print-routes, was added that takes in a module:callable, introspects the routes, and prints the results to stdout. This utility is automatically installed along with the framework:

    $ falcon-print-routes commissaire:api
    -> /api/v0/status
    -> /api/v0/cluster/{name}
    -> /api/v0/cluster/{name}/hosts
    -> /api/v0/cluster/{name}/hosts/{address}

Finally, falcon.get_http_status() was implemented to provide a way for apps to look up a full HTTP status line, given just a status code.

status = falcon.get_http_status(719)

Thanks again to all of our awesome contributors who have made these releases possible!

@kgriffs

Falcon WSGI Framework: 0.3.0

2015-06-15T21:09:00Z

Version 0.3 of the Falcon WSGI framework is now available, thanks to all the hard work put in by our growing team of stylish and talented contributors. Extra special thanks to everyone who joined us at the PyCon 2015 sprint in Montreal!

So what’s new in Falcon 0.3?

New Router

Thanks to Richard Olsson we now have a new engine that compiles routes into a decision tree. This improves lookup performance for large APIs, and will also allow us to more efficiently implement some new URI template features. As part of this work, we also made it easier to use custom routing engines.

In version 0.2, Falcon’s default router compiles each URI template to a regular expression. For each incoming request, Falcon iterates through this list of regexes, attempting to match each one, in turn, against the requested path. This means that the order in which routes are added can make a big difference in performance; when a path is requested for a route toward the back of the list, a bunch of regex match operations must be attempted before finding the correct route.

The new engine, by contrast, takes a divide-and-conquer approach to match a given request path to a resource. This works well because developers tend to organize APIs hierarchically. Richard and I started with a couple of prototypes that implemented a generic routing engine. This engine traversed a tree of nodes, with each node representing a single path segment in the URL namespace.

We found that the most efficient of the two prototypes ran slightly faster when looking up a long path with multiple segments. It wasn’t quite as fast for a simple path, but was still competitive. The order in which routes were added to the regex-based router also made a big difference; when looking up a route that was defined later in the router’s search list, the prototype’s divide-and-conquer approach easily won out.

The final engine incorporated into Falcon 0.3 takes this strategy one step further. It generates a static decision tree, rather than running a generic traversal algorithm over an abstract tree. The generated code looks something like this:

def find(path, return_values, expressions, params):
    path_len = len(path)
    if path_len > 0:
        if path[0] == "parks":
            if path_len > 1:
                params["park_id"] = path[1]
                if path_len > 2:
                    if path[2] == "map":
                        if path_len == 3:
                            return return_values[11]
                        return None
                    return None
                if path_len == 2:
                    return return_values[10]
                return None
            return None
        if path[0] == "libraries":
            
            # ...

This provides an extra boost of performance by avoiding looping constructs and dict lookups. It’s especially fast when JITed under PyPy.

New URI Template Feature

Also thanks to Richard Olsson, URI templates can now include multiple parameterized fields within a single path segment. For example, you might use this template to route a GH-style request:

/repos/{org}/{repo}/compare/{usr0}:{branch0}...{usr1}:{branch1}

Our new engine paves the way for implementing some other, long-overdue templating features as well. Stay tuned!

Cookie Support

Thanks to the tireless efforts of Henrik Tudborg, we now have support for reading and writing cookies. A cookie can be read from the request via the new cookies property, which returns a simple dict:

cookies = req.cookies
my_cookie_value = cookies['my_cookie']

You can also set cookies on a response with the new set_cookie method:

resp.set_cookie("my_cookie", "my cookie value",
                max_age=600, domain="example.com")

Jython 2.7 support

During the PyCon 2015 sprint, Clara Bennett added support to Falcon for Jython 2.7. Now you can use Falcon along with Clamp and Fireside (or ModJy) to create JVM-friendly web services in Python!

Other goodies

The Request class gained a new helper, get_param_as_date(...), for getting a query param as a date.
Date header values are now returned as datetime objects, rather than raw string.
Friendly constants for status codes were added, so that you can now say falcon.HTTP_NO_CONTENT instead of falcon.HTTP_204.
Query string parsing was made much more robust when decoding embedded documents, such as JSON.

Security for Humans

2015-04-07T21:09:00Z

Lately I’ve been thinking about an interesting interplay between a person’s:

Desire to be productive (D)
Appreciation for security (S)
Faith in those who are implementing security measures (F)
Pain threshold for said security measures (T)

Where an individual’s security threshold is equal to some measure of the other three:

T = S + F - D

When designing any system, the amount of pain (degradation to the user’s experience) caused by security controls is simply the sum of the parts:

P = sum(pain(c) for c in controls)

Ideally, we want to create systems where the pain introduced by security controls does not exceed the threshold of its users:

P <= T

It’s tempting to become fixated on the right side of the equation, i.e., “the users are the problem.” Why? Because reducing (P) is hard. It requires formal threat modeling, creative architecture, and sufficient funding.

I don’t mean to say that working on (T) is completely wrong; in fact, you should absolutely strive to engender a healthy appreciation for security, and work to build relationships of trust between those implementing security measures and those affected by said measures. However, to be successful you’ll need to dig in and get to work on (P) as well. The problem with betting too much on (T) is that it lies in the realm of culture. Changing culture is a slow and difficult process. And it’s a process that can easily backfire.

Don’t demonize your users. This only sets the stage for a security cold war. Instead, shift the burden to design-time. Find ways to defend against threats without hamstringing users, and they will love you for it.

A Better uuidgen

2015-03-03T21:09:00Z

Recently, I put together some examples to use in a RESTful workshop, and needed to generate a bunch of UUIDs.

On OS X I have a couple of options. First, there’s uuidgen:

$ uuidgen
E4B221B0-9466-4354-8A33-5B3EB5D3ABE3

Under OS X, this creates a DCE version 4 (random) UUID. However, under FreeBSD, uuidgen always generates a version 1 UUID. And finally, under Linux, uuidgen can create either version 1 or version 4 UUIDs, but defaults to a random UUID when a high-quality RNG is available.¹

The second option I have on my MBP is the OSSP uuid tool. It’s also available on Linux and FreeBSD:

$ uuid
1d98d052-c107-11e4-a360-6796fc8cedc1

By default, uuid returns a DCE version 1 (time + MAC) UUID. I can override this to get a random UUID, which is usually what you want:

$ uuid -v 4
07158102-962d-4038-a3d6-fc6428b98313

Now I have a cross-platform way to generate a version 4 UUID from the command line. Next I need to get that value into my clipboard.

Trailing newlines with uuidgen and uuid

Both uuidgen and uuid output a trailing newline character. Now, that’s fine when just displaying the UUID in a terminal, but is decidedly less helpful when piping the UUID somewhere, for example to the clipboard:

$ uuidgen | pbcopy

Now when I paste the copied text somewhere else, like into a JSON document, the newline messes up my formatting (yes, I know, this is all very sad.)

{
    "uuid": "07158102-962d-4038-a3d6-fc6428b98313
"
}

A better uuidgen

Fortunately, the problems above are easily solved with a little bash magic. The systems where I run this have CPRNGs, so I’m comfortable with forcing version 4:

#!/usr/bin/env bash

if [ -t 1 ]
then
    uuid -v 4
else
    uuid -v 4 | tr -d '\n'
fi

This script first tests whether output is attached to a terminal. If so, a version 4 UUID is output with a trailing newline. Otherwise, if we are piping the output, we’ll strip off the trailing newline character.

Or, if you don’t want to depend on OSSP’s uuid tool:

#!/usr/bin/env python

import sys
import uuid

result = str(uuid.uuid4())
if sys.stdout.isatty():
    print(result)
else:
    sys.stdout.write(result)

The Python uuid.uuid4() function will use your operating system’s native uuid_generate_random function call, if available, to generate the UUID. Failing that, it will use os.urandom. Only if a CPRNG is unavailable will uuid.uuid4() resort to using random.randrange(256) like some kind of primitive animal.²

Now I have a version of uuidgen that works consistently across platforms, and is pipe-able.

Hooray!

¹I suppose this makes some kind of sense, since a bad generator would be more likely to introduce collisions. You also don’t want to lull the user into a false sense of security (allowing them to assume their UUIDs are unpredicatable and opaque when they actually aren’t).
²If you have to use such a platform, you have my sympathy.

OpenStack Paris Summit Retrospective

2014-12-17T21:09:00Z

A few weeks ago I attended the OpenStack Summit in Paris. For this next development cycle (“Kilo”) I decided to step down from the Program Technical Lead (PTL) role for Zaqar in order to give others the opportunity to lead, and to give myself more time to focus on a few other projects that have been demanding more and more of my attention. The new PTL, Flavio Percoco, is an amazing engineer and a good friend of mine; I know he is going to do a great job with Zaqar going forward. As any former or current PTL will tell you, it is far from an easy job, and I’m grateful to Flavio for stepping up to lead the program.

During the week of the summit, I observed three important trends in the OpenStack ecosystem. First, private clouds are starting to take on the characteristics of public clouds. Second, design discussions and general interactions between various members of the community are becoming significantly more civil and constructive. And finally, interns are taking a greater role in delivering new features across various OpenStack projects.

OpenStack is growing up. For anyone attending the Paris Summit, it was hard to miss the strong interest by banks, telcos and large enterprises in leveraging OpenStack within their data centers. The economics, flexibility, and control provided by OpenStack is (continuing) to attract some big players. It is my belief that as more organizations like BMW, BBVA, Bloomberg, Comcast/NBC, Time Warner, AT&T, Orange, Swisscom, and Huawei continue to adopt the open cloud in critical parts of their infrastructure, more and more private clouds will start looking like public clouds in terms of scale and other requirements. This will necessitate a dramatic improvement in the technical underpinnings of various projects, including performance, security, reliability, scale, and operability.

In order to deliver on these challenging requirements, active technical contributors and community leaders will need to be more disciplined and efficient than ever before. At this past summit I was happy to discover that community members were spending less time arguing about who is right, and more time discussing what is right; with a tacit acceptance that the community will need to embrace multiple technologies and deployment options in order to cover all of our emerging use cases.

Any creative endeavor of significance is the product of an extraordinary number of ideas; if we want to create a world-class open cloud solution, we must become incredibly efficient at farming great ideas and crafting them together. We must have a culture in which every voice is heard and valued, with individuals holding themselves accountable to create a constructive, positive community. “Seek first to understand,” as Stephen Covey would say. We aren’t simply building up software; we are building up people. Do that well, and the software will take care of itself.

One of the best sources of fresh ideas in the OpenStack community is our growing network of interns. During the summit in Paris I had the opportunity to spend time with several interns who are doing amazing work across a number of projects. These young professionals are our future leaders. They bring a fresh perspective to their respective teams, helping all of us challenge long-held assumptions and see the forest for the trees. I hope that we will continue to see more and more interns participating in OpenStack through such means as the GNOME Outreach Program for Women, Google Summer of Code, and general corporate sponsorships.

OpenStack will have a bright future if we can strike while the iron’s hot. Let’s take the Big Private challenge head-on, focusing our development efforts on efficiency, security, reliability, usability and operability. Let’s continue creating a more constructive, positive software development culture. And finally, let’s continue to invest in our future leaders through mentoring and internship programs.

Redis Lua Scripting for Performance

2014-11-19T21:09:00Z

Lately I’ve been working on Zaqar’s new Redis driver. Zaqar provides a stateless REST API for creating and consuming message feeds. When there are multiple observers AKA subscribers of a feed, each observer uses a marker to keep track of its own position in that feed.

In this design, there is a race condition that emerges as a result of the interplay between producers and observers, that can cause observers to miss one or more messages. This issue manifests differently depending on which backend you use with Zaqar, but generally speaking, to avoid the condition you need to make sure a message with a higher marker is never persisted before a message with a lower marker.

The way we originally dealt with this in the Redis driver was to use the server’s support for transactions. To do this with Redis, you set a watch on a key (or set of keys) upon which the transaction depends, then prepare the transaction by creating a pipeline of commands, and finally attempt to execute that pipeline. An error will be raised if any of the watched keys have changed in the meantime, causing all commands to abort.

Here is a version of the code in Zaqar that we originally used to post messages, edited for instructional purposes:

with self._client.pipeline() as pipe:

    start_ts = timeutils.utcnow_ts()

    # NOTE(kgriffs): Retry the operation if another transaction
    # completes before this one, in which case it may have
    # posted messages with the same rank counter the current
    # thread is trying to use, which would cause messages
    # to get out of order and introduce the risk of a client
    # missing a message while reading from the queue.
    #
    # This loop will eventually time out if we can't manage to
    # post any messages due to other threads continually beating
    # us to the punch.

    # TODO(kgriffs): Add a backoff sleep between retries

    while (timeutils.utcnow_ts() - start_ts) < RETRY_POST_TIMEOUT:
        now = timeutils.utcnow_ts()
        prepared_messages = [
            Message(
                ttl=msg['ttl'],
                created=now,
                client_uuid=client_uuid,
                claim_id=None,
                claim_expires=now,
                body=msg.get('body', {}),
            )

            for msg in messages
        ]

        try:
            # NOTE(kgriffs): Keep an eye on the side counter; if
            # it changes, we know another parallel request beat us
            # to the punch and we need to get a new starting
            # value for rank_counter.
            pipe.watch(counter_key)

            rank_counter = pipe.get(counter_key)
            rank_counter = int(rank_counter) if rank_counter else 0

            pipe.multi()

            for i, msg in enumerate(prepared_messages):
                msg.to_redis(pipe)
                pipe.zadd(msgset_key, rank_counter + i, msg.id)

            pipe.incrby(counter_key, len(keys))
            pipe.execute()

        except redis.exceptions.WatchError:
            continue

As you can see, Zaqar uses an ordered set to index messages. It ranks the messages using a side counter. Elsewhere in the Redis driver, there is a method that lists messages. The client provides a marker which tells the server the position of the last message received by that client, and then the server is responsible for returning the next batch of messages for that client.

In the Redis driver, the marker is simply the message ID. In order to return to the client a list of messages after the specified marker, the service looks up the rank of that marker in the message index, then lists any subsequent messages, in rank order, up to a specified limit.

This works, but the more concurrent requests served, the more frequent the counter collisions. The result is a lot of wasted CPU capacity spent on retrying the operation, and significantly higher per-request latency. There are strategies that can reduce the number of retries (on average) required, but they only offer marginal improvements.

Fortunately, there’s a better way.

Since version 2.6, Redis supports server-side execution of Lua scripts. This is analogous to stored procedures in the RDBMS world. However, only one Redis script may run at a time, and no other commands may run concurrently. In this way you can execute a batch of commands atomically, without having to use watch-abort-retry loops in the client. On the other hand, this also means scripts must finish quickly to avoid starving other incoming commands.¹

Generally speaking, NoSQL tends to force a lot of data model logic into the app layer. By supporting server-side Lua scripting, Redis provides a way to move some of that logic back into the data layer without having to add higher-order operations to the API.

All things considered, I had a hunch that moving the indexing logic to Lua would increase the performance of posting messages to the service. I was hoping for at least a moderate improvement over the transactional approach outlined above.

The first thing I noticed was that by moving much of the logic to Lua, I was able to greatly simplify the Python code:

with self._client.pipeline() as pipe:
    message_ids = []
    now = timeutils.utcnow_ts()

    with self._client.pipeline() as pipe:
        for msg in messages:
            prepared_msg = Message(
                ttl=msg['ttl'],
                created=now,
                client_uuid=client_uuid,
                claim_id=None,
                claim_expires=now,
                body=msg.get('body', {}),
            )

            prepared_msg.to_redis(pipe)
            message_ids.append(prepared_msg.id)

        pipe.execute()

    # NOTE(kgriffs): If this call fails, we will return
    # an error to the client and the messages will be
    # orphaned, but Redis will remove them when they
    # expire, so we will just pretend they don't exist
    # in that case.
    self._index_messages(msgset_key, counter_key, message_ids)

The _index_messages method prepares the arguments, then passes them to the cached Lua script:

def _index_messages(self, msgset_key, counter_key, message_ids):
    # NOTE(kgriffs): A watch on a pipe could also be used to ensure
    # messages are inserted in order, but that would be less efficient.
    func = self._scripts['index_messages']

    arguments = [len(message_ids)] + message_ids
    func(keys=[msgset_key, counter_key], args=arguments)

The Lua script then updates the message index using a single² ZADD call, then increments the side counter:

-- Read params
local msgset_key = KEYS[1]
local counter_key = KEYS[2]

local num_message_ids = tonumber(ARGV[1])

-- Get next rank value
local rank_counter = tonumber(redis.call('GET', counter_key) or 1)

-- Add ranked message IDs
local zadd_args = {'ZADD', msgset_key}
for i = 0, (num_message_ids - 1) do
    zadd_args[#zadd_args+1] = rank_counter + i
    zadd_args[#zadd_args+1] = ARGV[2 + i]
end

redis.call(unpack(zadd_args))

-- Set next rank value
return redis.call('SET', counter_key, rank_counter + num_message_ids)

Since only one Lua script can run at a time, the counter is guaranteed to stay constant while updating the index. Consequently, after the ZADD call, the ordered set is guaranteed to end up with a run of unique rank values for each batch of messages.

So how did it perform?

I benchmarked both the old and new implementations using zaqar-bench, a simple python+gevent performance testing tool included with Zaqar. I ran the tool with 3,000 producer clients, posting messages to a minimal Zaqar deployment (1 web head running uWSGI and one DB box running a couple of Redis processes).

Before

Before the patch the results were decent. But, as you can see, some requests took an inordinate amount of time. High contention for the side counter caused some requests to retry the transaction many times before finally succeeding.

req/sec: 5223

ms/req (mean): 3.5 
ms/req (stdev): 7.7 
ms/req (99th): 42.1
ms/req (max): 186.5

After

After applying the Lua patch and re-running the benchmark, the stats not only smoothed out significantly, but throughput jumped by almost 60%. Hooray!

req/sec: 8246

ms/req (mean): 2.4
ms/req (stdev): 1.7 
ms/req (99th): 10.7
ms/req (max): 54.6

There’s still some work to do in order to get those outliers fully under control, but these initial results have me excited to see what else a little Lua love can do.

¹Larger operations can typically be broken down into smaller ones in order to interleave multiple concurrent requests.
²This should be faster than multiple ZADD calls, since the Redis code still treats Lua scripts as clients, albeit ones that can bypass the network stack. However, I still need to do an A/B test to see if the difference in performance is significant.

Open Minds for Open Discussions

2014-09-30T21:09:00Z

I’m thinking about setting up a mailing list for the Falcon web framework. This seems like a good way to bring more people into the conversation, and it should help capture tribal knowledge for posterity.

But I have a concern. Mailing lists tend to dehumanize people, opening the door to subconscious (and conscious) social behaviors that are anything but constructive. I’ve seen this happen first-hand in other communities I’ve been a part of.

Here’s a rough list of ways to interact with people, from most human to least:

In-person visits
Video conferencing
Phone calls
Instant messaging
Mailing lists

Don’t get me wrong; mailing lists can be (and have been) used for much good. It’s just that the further down you get on the list above, the more discipline is required to keep communications constructive.

Part of the problem is that mailing lists (and other forums that facilitate open discussions) can sometimes lead to a culture of distrust or even become a tool for subversion. This happens when individuals humiliate, intimidate, or even bully others in the community. The more abstract and unaccountable the communications medium, the easier it is for those with good intentions to unconsciously use a poor choice of words. Not only that, but it also becomes easier for unscrupulous individuals to manipulate the community for personal gain.

I have to hope that most of the time these sorts of communications (or mis-communications, as the case may be) happen unconsciously, perhaps due to a lack of shared context or as a failed attempt at humor.

Regardless of whether the intent is actual or perceived, the damage to the community is the same, and must be dealt with immediately, before it festers into a community-crippling culture of enmity. We aren’t always going to agree on how this or that should be done. But we can agree to treat each other with trust and respect.

We can agree to seek first to understand.

Once the Falcon mailing list is live, it will be interesting to see how this plays out and how much moderation will be required. So far the community has been really cool and I don’t want to lose that.

I’m hoping people will for the most part moderate themselves, behaving professionally and being cognizant of the way their words may be perceived. If we can all do that, while also assuming good intent when on the receiving end, we’ll be well on our way to building a fantastic community around Falcon.

How to Win

2014-06-18T21:09:00Z

Allow me to share with you a personal experience.

It’s early summer, 1996. I am 16 years old, discovering muscles I never thought existed, holding a heavy baritone bugle in front of my body for interminable lengths of time. Every day, all day, I spend practicing with my corps, refining our field show for this year’s season. My fellow drum corps friends surround me as we perform our drills, practice our steps, and perfect our music under a hot blue sky.

During breaks we gossip about our corps, and about the competition. We talk about how everyone’s shows are shaping up, speculating on who will rock the DCI finals at the end of the summer. As the season progresses, two junior drum and bugle corps begin to stand out.

Everyone is talking about the Blue Devils and the Phantom Regiment.

The Blue Devils are based in Concord, CA. To date, they have won more championships than any other DCI corps. The Blue Devils' center snare is nicknamed “Jesus” because he never makes a mistake! They have a massive, tiered organization. Many of their musicians move out to California in late spring to practice and take private lessons in advance of the regular season.

The Phantom Regiment hails from Rockford, Illinois. They have yet to win a single DCI championship. And things are not looking promising this year, either. In fact, the Phantom Regiment has not been placing particularly well in the early-season competitions. The critics deride the Regiment’s “boring” show, which eschews the flashy Broadway-esque style favored by many DCI corps over the past few seasons.

But lately, we start to hear how the Phantom Regiment is placing higher and higher in competitions across the country, even taking first in some cases.

Now, when people talk about the Phantom Regiment, they use words like “exciting”, “powerful” and “precise”. The corps is building a fervent fan base with a back-to-basics show that is—somehow—incredibly refreshing.

Finally, at the end of the summer, when the Blue Devils and the Phantom Regiment meet in Florida for the DCI 1996 World Championships, they finish their individual shows to thunderous applause. It is clear to all of us that we have just seen something extraordinary.

At the end of the competition, all of the finalists take the field to await the judge’s decision. Starting with 12th place, as each corps' score is announced, the tension slowly builds… we are now waiting to hear who will be this year’s DCI World Champion…

In fourth place with a final score of 93.8…the Cavaliers!

In third place with a score of 96.9…the Cadets of Bergen County!

Then, a pause… There are only two corps left. The crowd begins to buzz with speculation. Who will take second? Who has won the championship? And then the announcement comes…

“Ladies and gentlemen, with a score of 97.4, for the first time in DCI history, we have a tie between the Blue Devils and the Phantom Regiment!”

The crowd goes absolutely insane.

❧

In 1996 the Phantom Regiment won against all odds. You can too:

Set Audacious Goals. Don’t settle for mediocrity. Dream big.
Es Sprit de Corps. Don’t underestimate the importance of creating a positive, constructive culture. A culture where every individual’s contribution is valued. A culture of friendship, respect, and accountability.
Obsess Over the Basics. When you are the underdog, your only chance of winning is to become obsessed with the basics. Prioritize quality over quantity; substance over flash.
Create Your Own Fans. There is more than one way to win. Decide who you’re playing for, and then create something that blows them away. Play for your fans, not your competition.

Falcon WSGI Framework: 0.1.8

2014-02-04T21:09:00Z

I’m quite proud of the new Falcon 0.1.8 release. Thanks to our growing community of talented contributors, we were able to ship several long-awaited goodies, including request sinks, improved URI decoding, and custom error handlers.

Also, there was a ton of work done to improve performance in hot code paths, in order to offset the extra processing required by the new features landing in 0.1.8.

Custom Error Handlers

You can now DRY up your error code by registering global handlers. An error handler is just a callable that takes the exception that was raised, plus the standard req and resp args that were passed to the responder, along with the params dict that was passed as kwargs to the responder.

def handle_storage_error(ex, req, resp, params):
    # Log what happened

    # ...

    # Return an appropriate response explictly, or raise an
    # instance of HTTPError as shown here...

    description = ('Sorry, couldn\'t write your thing to the '
                   'database. It worked on my box.')

    raise falcon.HTTPError(falcon.HTTP_725,
                           'Database Error',
                           description)


api = falcon.API()

# If a responder ever raised an instance of StorageError, pass control to
# the given handler.
api.add_error_handler(StorageError, handle_storage_error)

Alternatively, you can define a handler on the error class itself. If you name it handle then you don’t even need to specify the function in add_error_handler:

class StorageError(Exception):
    @staticmethod
    def handle(ex, req, resp, params):
        description = ('Sorry, couldn\'t write your thing to the '
                       'database. It worked on my box.')

        raise falcon.HTTPError(falcon.HTTP_725,
                               'Database Error',
                               description)

# ...

# Falcon conveniently assumes the handler is defined as `StorageError.handle`
api.add_error_handler(StorageError)

Request Sinks

Request sinks is another handy new feature added in Falcon 0.1.8. What you do is add a regex-based route that slurps up anything that starts with the given pattern. You can make smart proxies with this, or anything else you like.

Here’s a ridiculously contrived example that drains any request paths that start with either ‘/v1/charts’ or ‘/v1/inventory’.

# Step 1: Define a sink using an extra Proxy thing just for fun
class Proxy(object):
    def forward(self, req):
        return falcon.HTTP_503


class SinkAdapter(object):

    def __init__(self):
        self._proxy = Proxy()

    def __call__(self, req, resp, **kwargs):
        resp.status = self._proxy.forward(req)
        self.kwargs = kwargs


# Step 2: Invoke some magic
app = falcon.API()

sink = SinkAdapter()
app.add_sink(sink, r'/v1/[charts|inventory]')

# Step 3: Profit!

Case-Insensitive Headers

Previously, when you set response headers, the header name you used was case-sensitive. This wasn’t exactly intuitive in the world of HTTP, where clients and servers are supposed to treat header names as case-insensitive. Among other things, this created an unfortunate gotcha for folks who were trying to proxy requests to a backing service, and selectively overwrite some of the original header values.

Now, when setting headers, their names are normalized to lowercase to avoid this problem. This approach is more performant than using some kind of case-insensitive dict under the covers, and well-behaved clients should be treating response headers they get back from the server as case-insensitive anyway.

That being said, if some of your unit tests were asserting on specific header strings, they may break. If you are using falcon.testing.StartResponseMock, you can work around this problem by reading headers via headers_dict which is now implemented using a case-insensitive dict class borrowed from the stupendous Requests library.

Improved URL encoding/decoding

Percent-encoded characters in query strings are now properly decoded. Even encoded UTF-8 sequences work like a charm! See also RFC 3986 if you want to know how this is supposed to work and/or you are having trouble falling asleep.

Also, you can now manually encode/decode URI things in your app if you’re crazy like that; just from falcon.util import uri and you’re ready to rock.

Improved Python 3.3 Performance

All WSGI frameworks I’ve tested slow down when running under Python 3.3, relative to Python 2.7, but thanks to some serious voodoo, Falcon’s own performance gap has narrowed quite a bit as of 0.1.8. The difference is now just 12 μs/req. Check out the latest benchmarks and see for yourself.

Please, take 0.1.8 for a spin and tell me what you like, what you don’t, and what you would like to see in the next version. As always, you can find me on Freenode in #falconframework and on Twitter @kgriffs.

Get it while it’s hot.

Standardization Manifesto

2014-01-08T21:09:00Z

Standardization is often promulgated as a worthy goal for teams and communities, but it must be recognized for what it is: a Platonic ideal. It is far more practical to simply constrain the number of options to a small number. Even then, you must be prepared to make an occasional exception simply to get the job done.

I don’t think chaos is the answer, where you end up with everyone doing something different. However, I don’t think totalitarian standardization is the answer, either.

It’s important to use the right tool for the job. And if the tool doesn’t exist, who’s to say it shouldn’t be created?

There are simply too many compromises—both in terms of community dynamics and software functionality—that have to be made in order to force everyone to use One Thing. In fact, the more code, people, and projects you have, the more compromises you will be forced to make.

People often justify draconian standardization efforts by invoking the cliché “reinventing the wheel”. In reality, this is almost always a false analogy. Can you imagine if we had stopped with this design?

When someone tells you “don’t reinvent the wheel,” they probably mean to say “don’t duplicate effort”, or “don’t repeat yourself” (DRY). The latter phrases avoid drawing a false analogy, but still have the problem of assuming that (1) duplicating effort is inherently bad, and (2) that the accused is guilty before being proven innocent.

As for (1), sometimes duplicating effort is a perfectly reasonable thing to do. Students recreate other people’s work all the time in order to learn. And in the process, they sometimes discover even better ways of doing things. Or they may find that one way happens to be more productive for some people than another way, simply due to psychological differences among individuals.

Regarding (2), maybe the accused is guilty and maybe they aren’t, but it makes a big difference whether or not you decide in advance that the person has nothing of value to add beyond what already exists.

Stephen Covey found in his research that highly successful people seek first to understand, and only then to be understood:

If you’re like most people, you probably seek first to be understood; you want to get your point across. And in doing so, you may ignore the other person completely, pretend that you’re listening, selectively hear only certain parts of the conversation or attentively focus on only the words being said, but miss the meaning entirely. So why does this happen? Because most people listen with the intent to reply, not to understand.

As you seek to understand another’s point of view, it helps to recognize that different things “feel” right to different people. When you standardize on One Thing, you gain some advantages with respect to knowledge and code reuse, but those are often offset by the loss in productivity that is inevitable when you force a significant portion of your community to use something that doesn’t feel natural to their way of thinking.

More importantly, by mandating One Thing, you dissuade people from experimenting with other things which may (or may not) some day prove to be better than the One Thing, or at least inform future revisions of the One Thing. I don’t pretend to know in advance what the Best Thing is, and neither should any other community member.

Indeed, community leaders should see themselves more as moderators, and less as presidents or dictators.

If you put Some Thing out there and let people try it, and you see, by its fruits, that it is Good, other teams will start picking it up. Before you know it, you’ll arrive at a natural standard. But this takes time. You must be patient. You must, as a community, experiment with Some Thing, pushing and prodding it from many different angles, discussing its merits and shortcomings. Not too much time; just enough to get an idea of Its practicality. Enough time to allow Darwin to do his job.

It is common to think “me vs. them”, but the most effective community leaders think “we” or “us”. They seek first to understand. Consider: was the project made for the process, or the process made for the project? Was the leader made for the community, or the community made for the leader?

If you have to push very hard to get people to adopt Your Thing, you are doing it wrong. You aren’t building the community; you are poisoning it.

Painless Py3K Unicode Magic

2013-12-20T21:09:00Z

Implementing Python’s magic string methods is tricky when it comes to Unicode characters and Py3K compatibility. If your strings contain non-ASCII characters, ostensibly innocent statements such as str(thing) blow up without warning. I recently came across this problem in OpenStack, and wanted to share the strategy we are using to work around it.

The first step is to standardize on wide strings throughout your code base, only converting to UTF-8 byte strings at the edges, when it is required to communicate with the outside world. This strategy minimizes the number of places text encoding bugs can hide.

Next, once you have normalized your code to use six.text_type in lieu of str, find everywhere you use string coercion. You will want to change all the expressions that look like this:

str(thing)

to this:

six.text_type(thing)

Finally, if you ever override the default magic string methods, you will need to do something like this (gist):

import six

class FooError(Exception):

    message = u'An unknown exception occurred.'

    # Called under both Py2 and Py3K for str(ex)
    def __str__(self):
        if six.PY3:
            return self.message

        # Avoid UnicodeDecodeError in py2 when the string
        # contains non-ASCII characters.
        return self.message.encode('utf-8')

    # Called under Py2 for unicode(ex) and ignored in Py3
    def __unicode__(self):
        return self.message


# elsewhere...

def do_something():
    raise FooError()

try:
    do_something()
except FooError as ex:
    # Returns a UTF-8 string in py2, and a wide string in py3,
    # both of type `six.text_type`, with no coercion. Normally you
    # would use `six.text_type` instead (see below)
    msg_a = str(ex)

    # Returns `unicode` in py2 and `str` in py3.
    msg_b = six.text_type(ex)

The result of __str__ under Py2 is always coerced to str when unicode is returned, which results in an ugly UnicodeDecodeError when the string contains non-ASCII code points:

>>> class BadLlama(object):
...     def __str__(self):
...         return u'€'
...
>>> badness = BadLlama()
>>> str(badness)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
UnicodeEncodeError: 'ascii' codec can't encode character u'\u20ac' in position 0: ordinal not in range(128)
>>>

Happy Hacking!

SHA Snake Oil

2013-11-25T21:09:00Z

Massive, highly-publicized security breaches of online services in recent years have exposed the inconvenient truth that many web services still use MD5-based password authentication, and some don’t even hash passwords in the first place.

This is serious stuff, considering that people tend to reuse the same password everywhere they go. A weak service not only risks its own business and reputation, but also everyone else’s.

Naive Password Hashing

In the wake of these attacks, a movement began¹ to stop storing passwords in such a blatantly insecure way. In some circles, using a simple salted SHA was promulgated as the “best practice” fix. While certainly better than storing passwords in plaintext, or hashing them with MD5, there are other, more appropriate algorithms we should be promoting instead.

Here’s the problem: SHA, just like MD5, is actually optimized for speed. In other words, just like MD5, SHA was designed to generate a one-way hash as quickly as possible. This is a good property to have in some cases, but when it comes to password hashing, the last thing you want is an efficient algorithm!

Case in point: Today’s commodity GPUs can perform billions of hashes per second². Armed with a few video cards (or an EC2 account) and some knowledge of how humans typically choose passwords³, it becomes trivial for an attacker to crack large numbers of passwords in a surprisingly short amount of time.

Use the Right Tool

What we as a community should be promoting, instead, is the use of strong key derivation functions (KDFs).

KDFs comprise a family of algorithms for generating password hashes. They can be used for password verification, as well as for deriving limited-use keys from a master secret. Unlike message-digest algorithms, such as MD5 and SHA, KDFs are designed to be inefficient. Proper use of a KDF goes a long way toward making brute-force attacks impractical to execute, in terms of both cost and time.

When asking people to move away from plaintext and MD5, we should be encouraging them to use a proper KDF, not some kind of home-grown, salted SHA digest.

That way, we make the black hats sad.

Here are my (current) go-to KDFs:

PBKDF2. This RSA-developed, NIST-recommended algorithm has been widely used and vetted by cryptographers. You can find it in anything from LastPass to Django, OS X to Android. PBKDF2 is a good choice if an scrypt library is not available for your programming language of choice.
scrypt. This KDF is relatively new and not as battle-tested as some older algorithms, but has the advantage of requiring lots of memory to go fast, which mitigates attacks that rely on specialized hardware.

We must do better

Everyone has a responsibility to the broader community to defend their portion of the web. Let’s ensure we are promoting real best practices as we work to raise the bar on computer security.

Caveat emptor: While I care deeply about computer security and have a working knowledge of the same, I’m no cryptographer. You should definitely invest some time into making your own evaluation of KDFs, including consulting with experts in the field to fully understand their proper use.

¹It’s about time our industry got a wake up call.
²With appropriate software, i.e. hashcat
³See also this password analysis.

An Unladen Web Framework

2013-07-02T21:09:00Z

When measuring the performance of a web service, I like to find out how quickly the service responds to requests (latency), and how much horsepower is required to serve each request (efficiency).

Efficiency is important because it allows me to serve large numbers of customers at a reasonable cost (both to them and to myself). Latency is also important to me, because it correlates with usability; if an API responds faster, then apps using that API respond faster, and by extension the people using those apps are happier, and more likely to spend more time with those apps. Yay!

Of course, there are many factors that influence web service latency and efficiency; one area that often gets overlooked or downplayed is the performance of the underlying web framework. Previously, I shared some performance testing results involving a queuing message service that used Rawr, a proprietary micro-framework I developed for Rackspace a few years back. Those results made it clear that even a small improvement in performance of the framework (in the case of Rawr, compiling it with Cython) can make a big difference in performance.

Several of you asked about getting the code for Rawr, and so I’m happy to announce that it’s successor, Falcon, has been open-sourced, courtesy of your friendly neighborhood Rackspace. If nothing else, I hope contributing this framework to the community will raise the bar on Python web framework performance, providing a laboratory of sorts for experimentation in this space.

Introducing the Falcon Web Framework

Falcon is a new, high-performance web framework for building web services and cloud APIs with Python. It’s WSGI-based, and works great with Python 2.6, Python 2.7, Python 3.3, and PyPy, giving you a wide variety of deployment options. While the project is still quite young (v0.1.6 at the time of this writing), it’s far enough along to be useful in real applications. In fact, we’re already trying it out in a few cloud projects at Rackspace.

Yet Another Web Framework

I didn’t particularly want to write Falcon. It would have been far easier to take something off the shelf and just plug it in. However, a few things pushed me over the edge:

Python web frameworks often perform rather poorly under load. At high concurrency, using async IO, API servers can become CPU-bound. When that happens, every microsecond counts. I wondered if I could make something that could perform a little better than your average framework.
Most web frameworks come with a lot of HTML-centric tooling that is fantastic if you are developing a web app, but quite useless for building an API. In that case, all they do is waste RAM, increase your chance of a security exploit, and generally make a nuisance of themselves.
Many frameworks try too hard, in my opinion, to abstract away what’s going on under the hood, making it difficult to reason about the river of HTTP flowing in and out of your API. Magic is wonderful at development time, but a nightmare when it comes time to debug a hairy production issue.

How is Falcon different?

First, Falcon is already pretty fast, and will be getting faster. When there is a conflict between saving the developer a few keystrokes and saving a few microseconds to serve a request, Falcon is strongly biased toward the latter.

Second, Falcon is lean. It doesn’t try to be everything to everyone, focusing instead on a single use case: HTTP APIs. Falcon doesn’t include a template engine, form helpers, or an ORM. When you sit down to write a web service with Falcon, you choose your own adventure in terms of async I/O, serialization, data access, etc. In fact, the only dependency Falcon takes is on Six, to make it easier to support both Python 2 and 3.

Third, Falcon eschews magic. When you use the framework, it’s pretty obvious which inputs lead to which outputs. Also, it’s blatantly obvious where variables originate. All this makes it easier for you and your posterity to reason about your code, even months (or years) after you wrote it.

When would you use Falcon?

I’m not going to pretend that Falcon is the best choice for all projects, or even the majority of them. Here are a few things to consider when choosing a web framework for your next project:

Reuse. If you constantly go back and forth between web app and API development, you may want to choose a less-specialized framework than Falcon, so you don’t have to context-switch between two different environments all day long. That being said, many apps these days serve static assets and render everything in JS, in which case Falcon could be a nice way to build the backing API.

Features. Falcon is a low-level framework, which gives you a lot of freedom, but also requires a little more elbow grease. If you just want to make a quick website or app, you might consider something with more bells and whistles than Falcon (e.g., Django, Pecan, or Flask)

Maturity. Falcon is still a young project and not as battle-tested as some other frameworks out there. Caveat emptor.

What does a Falcon-based web service look like?

Here is a simple example from Falcon’s README, showing how to get started writing an API:

# things.py

# Let's get this party started
import falcon


# Falcon follows the REST architectural style, meaning (among
# other things) that you think in terms of resources and state
# transitions, which map to HTTP verbs.
class ThingsResource:
    def on_get(self, req, resp):
        """Handles GET requests"""
        resp.status = falcon.HTTP_200  # This is the default status
        resp.body = ('\nTwo things awe me most, the starry sky '
                     'above me and the moral law within me.\n'
                     '\n'
                     '    ~ Immanuel Kant\n\n')

# falcon.API instances are callable WSGI apps
app = api = falcon.API()

# Resources are represented by long-lived class instances
things = ThingsResource()

# things will handle all requests to the '/things' URL path
api.add_route('/things', things)

You can run the above example using any WSGI server, such as uWSGI or Gunicorn. For example:

$ pip install gunicorn
$ gunicorn things:app

Then, in another terminal:

$ curl localhost:8000/things

Here is a more involved example that demonstrates reading headers and query parameters, handling errors, and working with request and response bodies.


import json
import logging
from wsgiref import simple_server

import falcon


class StorageEngine:
    pass


class StorageError(Exception):
    pass


def token_is_valid(token, user_id):
    return True  # Suuuuuure it's valid...


def auth(req, resp, params):
    # Alternatively, do this in middleware
    token = req.get_header('X-Auth-Token')

    if token is None:
        raise falcon.HTTPUnauthorized('Auth token required',
                                      'Please provide an auth token '
                                      'as part of the request',
                                      'http://docs.example.com/auth')

    if not token_is_valid(token, params['user_id']):
        raise falcon.HTTPUnauthorized('Authentication required',
                                      'The provided auth token is '
                                      'not valid. Please request a '
                                      'new token and try again.',
                                      'http://docs.example.com/auth')


def check_media_type(req, resp, params):
    if not req.client_accepts_json:
        raise falcon.HTTPUnsupportedMediaType(
            'Media Type not Supported',
            'This API only supports the JSON media type.',
            'http://docs.examples.com/api/json')


class ThingsResource:

    def __init__(self, db):
        self.db = db
        self.logger = logging.getLogger('thingsapi.' + __name__)

    def on_get(self, req, resp, user_id):
        marker = req.get_param('marker') or ''
        limit = req.get_param_as_int('limit') or 50

        try:
            result = self.db.get_things(marker, limit)
        except Exception as ex:
            self.logger.error(ex)

            description = ('Aliens have attacked our base! We will '
                           'be back as soon as we fight them off. '
                           'We appreciate your patience.')

            raise falcon.HTTPServiceUnavailable(
              'Service Outage',
              description,
              30)

        resp.set_header('X-Powered-By', 'Donuts')
        resp.status = falcon.HTTP_200
        resp.body = json.dumps(result)

    def on_post(self, req, resp, user_id):
        try:
            raw_json = req.stream.read()
        except Exception:
            raise falcon.HTTPError(falcon.HTTP_748,
                                   'Read Error',
                                   'Could not read the request body. Must be '
                                   'them ponies again.')

        try:
            thing = json.loads(raw_json, 'utf-8')
        except ValueError:
            raise falcon.HTTPError(falcon.HTTP_753,
                                   'Malformed JSON',
                                   'Could not decode the request body. The '
                                   'JSON was incorrect.')

        try:
            proper_thing = self.db.add_thing(thing)

        except StorageError:
            raise falcon.HTTPError(falcon.HTTP_725,
                                   'Database Error',
                                   "Sorry, couldn't write your thing to the "
                                   'database. It worked on my machine.')

        resp.status = falcon.HTTP_201
        resp.location = '/%s/things/%s' % (user_id, proper_thing.id)

wsgi_app = api = falcon.API(before=[auth, check_media_type])

db = StorageEngine()
things = ThingsResource(db)
api.add_route('/{user_id}/things', things)

app = application = api

# Useful for debugging problems in your API; works with pdb.set_trace()
if __name__ == '__main__':
  httpd = simple_server.make_server('127.0.0.1', 8000, app)
  httpd.serve_forever()

What’s next?

I need your help! Take Falcon for a test drive and tell me what you think.

Get Involved!

Contribute some docs and/or write a blog post
Improve the router’s support of URI templates
Create an optimized alternative to urllib.quote
Add more scenarios and frameworks to the benchmarking suite
Or choose your own adventure

The Face of the Cloud

2013-02-05T21:09:00Z

Lately I’ve been thinking about how it’s no coincidence that cloud computing and post-PC devices became popular at the same time. When Steve Jobs introduced Apple’s iPhone and it’s accompanying App Store, he kicked off a revolution in the way software was built and delivered. Jobs succeeded where others had failed by simply focusing on the user experience and letting the rest take care of itself.

The iPhone was only the beginning. Apple later introduced the iPad, and Google teamed up with cell phone manufacturers to deliver this new way of computing to the masses. In the past few years, we’ve also seen the wild success of Internet entertainment devices such as the Roku, fueled in large part by Netflix and Pandora. You can hardly find a game console, Blu-ray player or TV for sale that doesn’t use the Internet in some way. Combined, all these trends are pushing the concept of post-PC devices into ubiquity.

With millions of these devices sold and used every day around the world, it’s no wonder cloud computing has become such a hot topic. Post-PC devices crave content; they are portals to the world’s information, the world’s people, and the world’s markets. The cloud connects all of these things together and makes them accessible to anyone with an Internet connection.

But why didn’t all this happen years ago when tech heavyweights— Oracle, Sun, Novell and IBM, among others—were pushing thin client solutions? After all, aren’t post-PC devices just thin clients?

First, thin client solutions were designed with the IT department in mind, not the poor schmucks who would actually have to use the things for hours on end, day after day. The goal was to make the system administrator’s job easier while at the same time growing the market for Big Iron. This naturally led to clients that were too thin, too constrained, and too utilitarian. If you contrast thin clients with the iPhone and iPad, the Galaxy Note, even the MacBook Air, you start to understand the power of good design and capable hardware, working in tandem.

Second, thin-clients failed to create a revolution in computing because they were not mobile, and were sandboxed within corporate networks. The infrastructure simply wasn’t there. The Internet was immature, and cell phone networks barely had enough bandwidth for transmitting voices, let alone data. You simply can’t deliver a good experience over 56k.

Third, applications were too hard to use, too hard to write, and too expensive to buy. Thin clients didn’t solve any of these problems; the only thing they did was make IT Bob’s life a little easier than before; with thin clients, he didn’t have to go around manually installing and updating software on everyone’s machines. Contrast that situation with the democratized development and distribution of modern software.

Free, extremely productive development tools and online documentation make it easy for anyone to get started writing apps. App stores take the pain out of deploying, updating, and charging for software. Backend services are hosted on pay-as-you-go clouds (which often have free tiers), so that even cash-strapped college kids can create apps with a compelling online experience. These apps are generally more specialized than their dinosaur ancestors, making modern software both easier to use, and less expensive.

The cloud is a vital part of the post-PC world. Cloud computing is essential not only for democratizing software development, but also for freeing the world’s information. Let’s have more of that.

uWSGI vs. Gunicorn, or How to Make Python Go Faster than Node

2012-12-18T21:09:00Z

It seems I’ve finally arrived at the end of my quest to discover a fast, reliable Python stack for serving web APIs that can compete favorably with Node. The funny thing is, I didn’t even know it was my quest until I started looking at the surprising results from this latest round of performance testing, in which I pitted uWSGI against Gunicorn.

When it comes to deploying web APIs, my preference is to use something lean-n-mean for managing local sockets and WSGI workers, leaving macro load balancing, SSL termination, rate limiting and general HTTP heavy-lifting to the big guns (e.g., Stingray, Nginx, HAProxy, Stud).

Gunicorn has been my go-to WSGI server for hosting web APIs in production, due to its simplicity, performance, and manageability. Recently I re-discovered uWSGI and was pleasantly surprised to find how far it has come in the past couple of years. I was particularly impressed by uWSGI’s high configurability, including lots of production-friendly options.

Considering that uWSGI and Gunicorn are both pre-forking¹ WSGI servers, and given other design similarities, I couldn’t help but wonder how each would perform in the ring.

Teh Contenders

uWSGI (1.4.2). Here we have what appears to be a devops dream-come-true. Lots of production-friendly configuration options and a pluggable architecture for customizing stats reporting and anything else you can dream up (LZ4 compression, anyone?). uWSGI has matured quite a bit over the past couple of years, and now supports a plethora of languages and deployment options. Nginx supports the uwsgi protocol natively.

Gunicorn (0.16.1). My go-to WSGI server. Like uWSGI, Gunicorn supports different worker types. IMHO, Gunicorn provides a good balance between performance and usability. It’s been performing like a champ for me in production for the better part of a year.

Gevent (1.0rc1). This little green machine is mostly about coroutine-based async networking, but includes a pretty decent WSGI server, providing a good baseline that helps put uWSGI and Gunicorn’s performance into perspective.

Node.js (0.8.14). I rewrote my event queuing service in JavaScript ala Node to further put uWSGI and Gunicorn’s performance into perspective, and to find out how well a Python-based app could compete with one running on the highly-optimized, V8-backed Node platform.

Setup

The performance testing setup this time around was identical to the one I used previously to benchmark Gevent, Tornado, Cython, and PyPy. I brought forward the Cythonized version of my Rawr web framework for this latest round of tests. The Gevent and Node.js numbers you’ll see in the charts below were simply carried forward from my previous posts.

All tests involved a single worker and were either self-hosted (in the case of Gevent and Node.js), or used an external WSGI server (in the case of uWSGI and Gunicorn). Workers were configured to use gevent, so they would play nice with my app, which relies on greenlets ala gevent.monkey.patch_all().

As before, I tested a series of requests to a single event channel which was primed with ~1K of JSON-encoded data (i.e., the httperf workers had to read a little more than 1K per transaction). Keep-alive was not used, modeling the worst-case scenario in which every transaction involved negotiating a new TCP/IP connection.

I used the following command to run uWSGI:

uwsgi --http :8890 --file rse.py --gevent 2000 -l 1000 -p 1 -L

Here’s the command I used to run Gunicorn:

gunicorn \
  -b :8091 -w 1 -k gevent --worker-connections=2000 \
  --backlog=1000 -p gunicorn.pid --log-level=critical rse:app

Note that I disabled request logging in both cases.

Results

Throughput (req/sec)

Response Time (ms)

Errors

Standard Deviation for Throughput (req/sec)

Q.E.D.

uWSGI looks like the Python app server to beat, although it’s performance did become a bit erratic under high load. Not only is it ridiculously fast, but judging by the docs, uWSGI gives you a lot of great options for production tuning.

But what’s more, with an optimized web framework and uWSGI on your side, it looks like Python apps can hold their own against Node.

Now that’s something to think about.

¹ The term pre-forking, as used here, simply means that sockets are created before forking child processes, and that those sockets are inherited by the child processes so that they can directly bind to them, saving an extra hop.