Sinatra: Up and Running Alan Harris and Konstantin Haase Beijing • Cambridge • Farnham • Köln • Sebastopol • Tokyo Sinatra: Up and Running by Alan Harris and Konstantin Haase Copyright © 2012 Alan Harris. All rights reserved. Printed in the United States of America. Published by O’Reilly Media, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472. O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions are also available for most titles (http://my.safaribooksonline.com). For more information, contact our corporate/institutional sales department: (800) 998-9938 or email@example.com. Editors: Simon St. Laurent and Mike Hendrickson Production Editor: Melanie Yarbrough Proofreader: Melanie Yarbrough Cover Designer: Karen Montgomery Interior Designer: David Futato Illustrator: Robert Romano Revision History for the First Edition: 2011-11-21 First Release See http://oreilly.com/catalog/errata.csp?isbn=9781449304232 for release details. Nutshell Handbook, the Nutshell Handbook logo, and the O’Reilly logo are registered trademarks of O’Reilly Media, Inc. Sinatra: Up and Running, the image of a whip-poor-will, and related trade dress are trademarks of O’Reilly Media, Inc. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and O’Reilly Media, Inc. was aware of a trademark claim, the designations have been printed in caps or initial caps. While every precaution has been taken in the preparation of this book, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information con- tained herein. ISBN: 978-1-449-30423-2 [LSI] 1321480476 Table of Contents Preface . .................................................................... vii 1. Taking the Stage . . ...................................................... 1 Characteristics of Sinatra 2 Is It a Framework? 2 Does It Implement MVC? 2 Who’s Using It? 3 What Does a Production Project Look Like? 3 What’s the Catch? 4 Are These Skills Transferrable? 4 Installation 4 Thin 4 Up and Running 5 Breaking Down the Syntax 6 Testing with Telnet 8 Rock, Paper, Scissors or “The Shape of Things to Come” 10 Summary 13 2. Fundamentals . . ....................................................... 15 Routing 15 Hypertext Transfer Protocol 16 Verbs 16 Common Route Definition 18 Many URLs, Similar Behaviors 19 Routes with Parameters 20 Routes with Query String Parameters 21 Routes with Wildcards 21 The First Sufficient Match Wins 21 Routes with Regular Expressions 22 Halting a Request 23 Passing a Request 23 iii Redirecting a Request 24 Static Files 25 Views 27 Inline Templates 27 External View Files 28 Passing Data into Views 29 Filters 30 Handling Errors 31 404 Not Found 32 500 Internal Server Error 32 Configuration 34 HTTP Headers 34 The headers Method 35 Exploring the request Object 36 Caching 38 Setting Headers Manually 38 Settings Headers via expires 39 ETags 40 Sessions 42 Destroying a Session 43 Cookies 43 Attachments 44 Streaming 45 Keeping the Connection Open 46 Finite Streaming 47 Summary 47 3. A Peek Behind the Curtain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Application and Delegation 49 The Inner Self 50 Where Does get Come From? 51 Exploring the Implementation 52 Helpers and Extensions 53 Creating Sinatra Extensions 54 Helpers 55 Combining Helpers and Extensions 58 Request and Response 58 Rack 58 Sinatra Without Sinatra 59 Rack It Up 61 Middleware 61 Sinatra and Middleware 62 Dispatching 62 iv | Table of Contents Dispatching Redux 63 Changing Bindings 64 Summary 66 4. Modular Applications . . ................................................. 67 Subclassing Sinatra 68 Running Modular Applications 68 About Settings 71 Subclassing Subclasses 73 Dynamic Subclass Generation 76 Better Rack Citizenship 78 Chaining Classes 78 On Return Values 82 Using Sinatra as Router 83 Extensions and Modular Applications 85 Helpers 85 Extensions 86 Summary 87 5. Hands On: Your Own Blog Engine . . ....................................... 89 Workflow Concept 89 File-Based Posts 89 Git for Distribution 90 Semistatic Pages 91 The Implementation 92 Displaying Blog Posts 92 Git Integration 96 Glueing Everything Together 99 Summary 103 Table of Contents | v Preface When people speak of Ruby web development, it has historically been in reference to the opinionated juggernaut that is Rails. This is certainly not an unfounded association; Hulu, Yellow Pages, Twitter, and countless others have relied on Rails to power their (often massive) web presences, and Rails facilitates that process with zeal. Why, then, are people so interested in Sinatra, the tiny little domain-specific language that could? Rails was a breath of fresh air to many developers exhausted by the “old ways”; Sinatra enters the arena with a similar game-changer: a beautifully minimalistic, “I’ll get out of your way” approach. No generators, no complex folder hierarchies, and a brief yet expressive syntax that maps closely to the functionality exposed by the Hypertext Transfer Protocol verbs. In short, Sinatra is for classy web development. Our goal is to provide the core concepts and accompanying examples to help you feel comfortable using Sinatra as quickly as possible. By the end, you should have a working knowledge of Sinatra and how it fits into the larger Ruby web development ecosystem. You should know when Sinatra will get the job done quickly and when it might be better to lean on Rails, Padrino, or similar frameworks. You should also have a better sense of the internals of Sinatra, as well as the Rack specification and accompanying gem. No worries, we won’t short-change you on the reference aspects; you can certainly return to this book to recall how to perform daily tasks without excessive searching. With that said, let’s get you up and running. vii Who This Book Is For Sinatra: Up and Running is for developers with some Ruby experience under their belt, and ideally some web development experience as well. Some concepts that are core to web development (the HTTP specification, HTML, CSS, etc.) are critical to under- standing how to be productive with Sinatra; we recommend that you have at least a passing familiarity with these concepts to make the experience a little easier. If you’ve written some web applications before but not specifically in Ruby, that’s no problem. Our discussion of other tools is primarily limited to comparing and contrast- ing with how Sinatra does things. Our plan is to try to address the needs of several distinct camps of readers: those with a Ruby web development background in Rails but no experience with Sinatra, as well those who are familiar with Sinatra but would like a tour of its internals and philosophy. Where possible, we’d also like to help bring developers without direct web experience into the fold. Pretty tricky if you think about it, but we’ll do our best to speak to all the seats in the house by the conclusion. Given these stated goals, we’ve divided the materials into three sections. The beginning of the book focuses on the bare minimum you need to know to work with Sinatra. Here you’ll find the fundamentals, such as how to craft routes, manage sessions, create views, and so on. Immediately afterward, we will lift the veil and examine some of the tech- niques behind the scenes, which will open up a world of possibilities for implementa- tion and integration. Finally, we will wrap up the discussion with some practical ap- plications, including developing a GitHub-powered blog. We’ve also tried to inject as much related information as possible for the various topics covered within, ranging from gotchas to other re- sources where one could explore subtopics in greater depth. One aside: if you encounter a section explaining information you’re already well-versed in, please bear with us as other readers may benefit from the discussion. We strive to keep the pace brisk, but we’d prefer not to leave any folks out. How This Book Is Organized Sinatra: Up and Running is organized as follows. The Basics Chapter 1, Taking the Stage, serves as a high-level introduction to some of the core concepts in Sinatra. It also discusses how to install the Sinatra gem, and walks through the creation of a simple application. viii | Preface Chapter 2, Fundamentals, covers the different features of Sinatra, such as route defini- tions, creating views, managing sessions, and so on. It also serves as something of a reference chapter, with each topic discussed in granular fashion. If you’ve already built some Sinatra applications of your own and are fairly comfortable doing so, you can likely just skim through Chapters 1 and 2, although the newest release of Sinatra (version 1.3.1) contains a number of changes that are worth exploring (including support for the HTTP PATCH verb, streaming, etc.). Digging Deeper In Chapter 3, A Peek Behind the Curtain, we discuss the internals of Sinatra and its implementation; this includes coverage of Rack, building middleware, and other topics that clarify what really happens under the hood. Chapter 4, Modular Applications, covers the various approaches available for subclass- ing Sinatra, allowing you to create significantly more flexible and robust architectures. If you’ve built some Sinatra applications but have never really explored the source code (or written Rack applications directly), this section will help to flesh out your knowledge. Understanding the modular applica- tion approach is critical to taking full advantage of what Sinatra offers. Hands On In Chapter 5, Your Own Blog Engine, we put the theory into application and create a Markdown-powered blog that takes advantage of the service hooks provided by the GitHub API. Conventions Used in This Book The following typographical conventions are used in this book: Italic Indicates new terms, URLs, email addresses, filenames, and file extensions. Constant width Used for program listings, as well as within paragraphs to refer to program elements such as variable or function names, databases, data types, environment variables, statements, and keywords. Constant width bold Shows commands or other text that should be typed literally by the user. Preface | ix Constant width italic Shows text that should be replaced with user-supplied values or by values deter- mined by context. This icon signifies a tip, suggestion, or general note. This icon indicates a warning or caution. Using Code Examples This book is here to help you get your job done. In general, you may use the code in this book in your programs and documentation. You do not need to contact us for permission unless you’re reproducing a significant portion of the code. For example, writing a program that uses several chunks of code from this book does not require permission. Selling or distributing a CD-ROM of examples from O’Reilly books does require permission. Answering a question by citing this book and quoting example code does not require permission. Incorporating a significant amount of example code from this book into your product’s documentation does require permission. We appreciate, but do not require, attribution. An attribution usually includes the title, author, publisher, and ISBN. For example: “Sinatra: Up and Running by Alan Harris and Konstantin Haase (O’Reilly). Copyright 2012 O’Reilly Media, Inc., 978-1-449-30423-2.” If you feel your use of code examples falls outside fair use or the permission given above, feel free to contact us at firstname.lastname@example.org. Safari® Books Online Safari Books Online is an on-demand digital library that lets you easily search over 7,500 technology and creative reference books and videos to find the answers you need quickly. With a subscription, you can read any page and watch any video from our library online. Read books on your cell phone and mobile devices. Access new titles before they are available for print, and get exclusive access to manuscripts in development and post feedback for the authors. Copy and paste code samples, organize your favorites, down- load chapters, bookmark key sections, create notes, print out pages, and benefit from tons of other time-saving features. x | Preface O’Reilly Media has uploaded this book to the Safari Books Online service. To have full digital access to this book and others on similar topics from O’Reilly and other pub- lishers, sign up for free at http://my.safaribooksonline.com. How to Contact Us Please address comments and questions concerning this book to the publisher: O’Reilly Media, Inc. 1005 Gravenstein Highway North Sebastopol, CA 95472 800-998-9938 (in the United States or Canada) 707-829-0515 (international or local) 707-829-0104 (fax) We have a web page for this book, where we list errata, examples, and any additional information. You can access this page at: http://shop.oreilly.com/product/0636920019664.do To comment or ask technical questions about this book, send email to: email@example.com For more information about our books, courses, conferences, and news, see our website at http://www.oreilly.com. Find us on Facebook: http://facebook.com/oreilly Follow us on Twitter: http://twitter.com/oreillymedia Watch us on YouTube: http://www.youtube.com/oreillymedia Preface | xi CHAPTER 1 Taking the Stage To begin, let’s take a moment to address a specific question: “what exactly is Sinatra?” We’ll start with a somewhat broad, sweeping answer, and spend the remainder of our time together drilling down into the finer details. Sinatra is a domain-specific language for building websites, web services, and web ap- plications in Ruby. It emphasizes a minimalistic approach to development, offering only what is essential to handle HTTP requests and deliver responses to clients. At a high-level, a domain-specific language is one that is dedicated to solving a particular type of problem. For example, SQL (structured query language) is designed to facilitate interaction with relational da- tabase systems. By contrast, a general-purpose language such as Ruby can be used to write code in many different domains. This is a somewhat simplified view of things; if you’re interested in delving deeper into the landscape of DSLs consider Martin Fowler’s excellent “Domain-Specific Languages” (Addison-Wesley). Written in less than 2,000 lines of Ruby, Sinatra’s syntax (while expressive) is simple and straightforward. If you’re looking to rapidly assemble an API, build a site with minimal fuss and setup, or create a Ruby-based web service, then Sinatra has quite a bit to offer. As we’ll see later, Sinatra applications can also be embedded into other Ruby web applications, packaged as a gem for wider distribution, and so on. In this chapter, our goal is to get off the ground as quickly as possible. We’ll install Sinatra and a supporting web server to host our application, then create a simple app that responds to an HTTP request. 1 A quick disclaimer: at the outset, the code we present will not have much in the way of robust error handling. Instead we will focus purely on the syntax required to express core concepts without distraction. In discus- sing the fundamentals (particularly in Chapter 2), we will establish the built-in mechanisms that Sinatra provides for handling faults of varying nature. Of course, normal Ruby best practices hold true; Avdi Grimm offers excellent coverage on the nuances of handling Ruby error conditions at http://exceptionalruby.com/. Characteristics of Sinatra We’ll get into Sinatra’s features and syntax in a moment; at the outset, it would be useful to define some parameters around what makes Sinatra distinctive and unique in the Ruby web ecosystem. Is It a Framework? Sinatra is not a framework; you’ll find no built-in ORM (object-relational mapper) tools, no pre-fab configuration files...you won’t even get a project folder unless you create one yourself. While it may not seem like it now, this can be quite liberating. Sinatra applications are very flexible by nature, typically no larger than they need to be and can easily be dis- tributed as gems. A notable example along these lines is Resque, a very handy job processor created by the folks at GitHub. If you happen to install it, you’ll find it comes with a Sinatra application that can be used to monitor the status of the jobs you create. Does It Implement MVC? Sinatra does not force you to adhere to the model-view-controller pattern, or any other pattern for that matter. It is a lightweight wrapper around Rack middleware and en- courages a close relationship between service endpoints and the HTTP verbs, making it particularly ideal for web services and APIs (application programming interfaces). 2 | Chapter 1: Taking the Stage Model-view-controller (specifically the Model2 variant common to the web) is a way of architecting applications that many web frameworks have adopted. Although these frameworks may have routing rules that are similar in some ways to Sinatra’s routes, they typically also enforce them strictly with requirements on folder names and project hierarchies. The Padrino Framework, available from http://www.padrinorb.com/, brings the Sinatra core into the MVC world. If you’re a Rails developer and find you’re missing some of the features it provides, you might want to give Padrino a try. Who’s Using It? GitHub, Heroku, BBC, thoughtbot, Songbird, Engine Yard, and many others are active users of Sinatra in production environments. You can rest assured that by learning and implementing Sinatra you are working with a tested and proven solution that supports a scalable, responsive web experience. Initially developed by Blake Mizerany, the continued development and support of Sinatra is provided by the team at Heroku. What Does a Production Project Look Like? Believe it or not, it’s not uncommon to find entire Sinatra applications encapsulated in a single physical file. You can certainly build larger applications, and we’ll cover some helpful ways to lay out applications throughout the course of the book. There are two primary approaches to building Sinatra applications: classic and modu- lar. They’re similar, but with a few caveats: you cannot have multiple classic applica- tions running in one Ruby process, and classic mode will add some methods to Object (which could be a problem if you want to ship your application as a gem). You can also create Sinatra apps on the fly, entirely in code, from within another application. What’s the difference between the two? Well, the quick answer is that in modular mode, you explicitly subclass Sinatra and build your application within that scope; in classic mode, you just require Sinatra and start defining endpoints. Both have their pros and cons, depending on your needs. We’re going to explore the classic style of Sinatra application first in this book, then dive a little deeper into Rack, modular applications, and so on. You’ll have a good sense of both methods shortly. Characteristics of Sinatra | 3 What’s the Catch? All these benefits sound great, but it doesn’t indicate that Sinatra is the correct choice for every web-facing application under the sun. If you’re looking to build the next gigantic social network, you certainly could do it in Sinatra, but it would require con- siderably more wiring on your part compared to the conveniences provided by a frame- work (such as Rails or Padrino). The choice of tools becomes one of balance, and you’ll need to make judgment calls based on the needs of the project. Later in the book we will demonstrate ways to better organize projects as they grow in scope. Any application can get away from you if you let it, and Sinatra applications are no exception. Are These Skills Transferrable? Beyond the close relationship it has with the underlying web protocols, Sinatra has also inspired a number of tools in languages such as Microsoft .NET (Nancy), Perl (Dancer), Lua (Mercury), and quite a few more. Investing time in learning Sinatra is not only beneficial by way of becoming better acclimated with the tools and protocols that power the web, but can also serve as a convenient springboard to grokking other languages. Installation Installing Sinatra is straightforward; from the command line, simply type gem install sinatra. At the time of this writing, the current version of Sinatra is 1.3.1. Earlier versions of Sinatra had some issues with the Ruby 1.9.x family. Since 1.2, Sinatra plays nicely with Ruby 1.9.2, but you should be aware of the potential for issues with older combinations. Thin The installation is brief and fairly unceremonious. When it’s finished, we recommend you also install the Thin web server by typing gem install thin. Sinatra will automat- ically use Thin to handle communication with clients, if it is available. Why Thin as opposed to other server options? Most Ruby web developers are familiar with WEBrick, a web server written entirely in Ruby. Zed Shaw later introduced Mon- grel, which gained popularity as a faster and more stable platform for Ruby web ap- plications. Thin continues this evolution by using code from Mongrel to parse HTTP requests but improves network I/O performance via EventMachine, which manages evented network communication. If Thin is not installed, Sinatra will first try to run with Mongrel, choosing WEBrick if Mongrel isn’t available either. 4 | Chapter 1: Taking the Stage Sinatra 1.3.1 adds a number of new features, notably support for stream- ing. At the moment, there is a known issue with WEBrick and streaming: the response from the server arrives at the client all at once. This is currently being addressed. For Windows users: depending on the specifics of your environment, you may need to build Thin from source. To do so, you’ll need to install a C compiler or opt for one of the Ruby development kit versions. You can certainly run Sinatra without Thin, but be aware that Thin is known to perform better under high load than both Mongrel and WEBrick. Up and Running It’s painless to get a Sinatra application off the ground. Open the text editor of your choice and enter the code in Example 1-1. The syntax is readable, but we’ll discuss the finer details in a moment. Example 1-1. A simple Sinatra application require 'sinatra' get '/' do "Hello, world!" end Save this file as server.rb. Once you’ve done so, type ruby server.rb at the command prompt. You should be notified that Sinatra has taken the stage, as shown in Figure 1-1. If you happen to still use Ruby 1.8 and you run into “no such file to load” exceptions, try ruby -rubygems server.rb instead. To avoid those extra characters, you can simply set the environment variable RUBYOPT to -rubygems. On Linux or Mac OS X, this can easily be done by adding RUBYOPT=-rubygems to your .bashrc in your home directory. By default, the application will listen on port 4567. You can select any available port by typing ruby server.rb -p port_num. Open a web browser and navigate to http://localhost:4567/. Your Sinatra application should respond with the cheerful greeting displayed in Figure 1-2. Up and Running | 5 Breaking Down the Syntax We’ve installed Sinatra and Thin, created a simple application, and verified that it responds properly to an HTTP GET request. So what’s happening under the hood? Sinatra is essentially a lightweight layer separating you as a developer from a piece of Ruby middleware called Rack. Rack wraps HTTP requests to help standardize com- munication between Ruby web applications and web servers. Sinatra abstracts Rack, allowing you to focus solely on responding to HTTP requests without worrying about the underlying plumbing. Figure 1-1. Sinatra has taken the stage Figure 1-2. The archetypical “Hello, world!” 6 | Chapter 1: Taking the Stage The only aspect that should look foreign to the average Ruby developer is line 3: get '/' do Here we get our taste of the Sinatra DSL syntax, which is typically expressed in the form verb ‘route’ do. In our code, we are instructing the application to respond to HTTP GET requests to the path '/'; our response is composed by the block we provided for behavior. This composite endpoint is referred to as a route. Sinatra applications respond to one or more routes to provide their functionality. This is part of the Sinatra magic; this code doesn’t look like a typical method definition because in actuality, it’s not. It’s actually a method call. Sinatra’s base class defines a handful of public methods matching the HTTP verbs (which we’ll discuss in depth in Chapter 2). The methods accept paths, options, and blocks. The block in Example 1-1 is the implicit return of “Hello, world!” and this is what gets evaluated deeper in the library. By making use of Ruby’s flexible nature with regard to brackets and parentheses, Sinatra is able to provide a syntax that reads quite naturally. It’s definitely worth taking a tour of the Sinatra source code at https:// github.com/sinatra/sinatra when time permits. Routes in your application are matched in top-down order; the first route that matches the incoming request is the one that gets used. This becomes an important point when we begin creating routes that include wildcards or other optional parameters where very different actions can occur depending on the values provided in the request. We’ll revisit this point with concrete examples in Chapter 2. This route is certainly on the simpler side of things; indeed the point is to demonstrate how little code it takes to create a “complete” application. More complex routes can respond to various HTTP verbs, contain wildcards, different types of pattern matches, and multiple routes can respond with the same action. We’ll greatly expand on routes in Chapter 2. Up and Running | 7 Testing with Telnet One critical key point when developing with Sinatra is that the program doesn’t respond to anything you don’t tell it to. We can see this quite clearly with a quick Telnet session, demonstrated in Example 1-2. From the command line, type telnet 0.0.0.0 4567 to establish a session with your application. Type the lines that are not italicized in the example below exactly as they appear. After the Host: 0.0.0.0 line, press return a second time. This ends the “headers” section, which we’ll talk more about in the next chapter. For now it’s sufficient to say that this tells the server you don’t have anything further to say and it should start processing. The lines that are italicized and indented are the responses from the web server. If you encounter any errors (such as the connection being closed) start Telnet again and ensure that each line is typed accurately. Example 1-2. Sending HTTP messages to a Sinatra application using Telnet [~]$ telnet 0.0.0.0 4567 GET / HTTP/1.1 Host: 0.0.0.0 HTTP/1.1 200 OK Content-Type: text/html;charset=utf-8 Content-Length: 13 Connection: keep-alive Server: thin 1.2.10 codename I'm dumb Hello, world! After connecting to the Sinatra application, we issued a GET request to the “/” route. The application promptly responded with our chipper greeting (and a tongue-in-cheek header identifying the codename for the latest version of Thin). Thin releases typically have codenames like in the example above. For example, version 1.2.2 is named “I Find Your Lack of Sauce Disturbing.” What would happen if we were to issue a POST to the application? Let’s give it a try; we’ll POST the payload “foo=bar” to the “/” route. The same rules apply; the non-italicized lines should be typed exactly as shown, there should be a blank line between Content-Length: 7 and foo=bar, and there should be a blank line after foo=bar. 8 | Chapter 1: Taking the Stage POST / HTTP/1.1 Host: 0.0.0.0 Content-Length: 7 foo=bar HTTP/1.1 404 Not Found X-Cascade: pass Content-Type: text/html;charset=utf-8 Content-Length: 410 Connection: keep-alive Server: thin 1.2.10 codename I'm dumb
Sinatra doesn't know this ditty.
post '/' do "Hello World" end