camping 2.1.532 → 3.0.0

data/book/08_publishing_an_app.md

@@ -0,0 +1,118 @@
+Once you've built your Camping app, you'll almost certainly want to get it online some place, so others can get at it! There are tons of ways to do this, some easy, some hard, some free, and some expensive. Some of these techniques also come with limitations.
+
+# Using a Rackup compatible host
+First make a config.ru file and fill it with goodies:
+```ruby
+# config.ru
+require 'camping'
+require 'camping/server'
+
+Camping::Server.start
+```
+
+If your app has any settings, like the port number, or the file where your camping app is located if it's not camp.rb, then pass those along as a hash:
+```ruby
+# config.ru
+require 'camping'
+require 'camping/server'
+
+Camping::Server.start({
+  :script => 'blog.rb',
+  :port => '80'
+})
+```
+
+# Using a spare computer
+Cost: Usually free; Limitations: None really; Extra Requirements: Need to have a computer you can leave on all the time.
+
+This is probably the easiest way. Just find a computer you can leave on all the time, and use The Camping Server on Port 80, by running something like this in the Command Prompt or Terminal:
+
+```
+camping --port 80 myapp.rb
+```
+
+Then check to make sure it's working by visiting http://localhost:80/ on that computer. Next, you'll need to find out if your internet provider gives you a Static IP address, or a Dynamic IP. Most home internet providers give you a Dynamic IP, where most business accounts come with a Static IP. If you don't know, you can find out by phoning your internet provider.
+
+# If you have a static IP address
+This is really a great situation to be in. You'll next want to get a domain name of some sort. You can register one on a Domain Name Registrar, but this will generally cost about $12 per year to keep. You can also get a free subdomain name from services like afraid.org. Regardless how you do it, you'll want to create an A Record, and for it's value, provide your IP address. You can usually find out your IP address by visiting an IP Lookup Website, or by asking your Internet Provider.
+
+# If you have a dynamic IP address
+Your IP Address will change from time to time, so you'll need to use a Dynamic DNS service. Popular DDNS services include Afraid.org, DynDNS, and No-IP. These will either require you to run a little program on your computer to watch when your IP changes and update the domain name, or have you enter a special username and password in to certain home routers.
+
+
+# Troubleshooting
+If you find others can't access your website through the domain name, and you have a dynamic IP, your Internet Provider might be applying Port Blocking. If you phone them, they might be able to remove the blocks. Otherwise, you'll need to run the camping server on a different port. 8080 is a common alternative. Of note, you'll need to include :8080 (or whatever) after the domain name and before the slash in your web address for this to work. For example: http://funkytown.afraid.org:8080/ - otherwise, make sure the DDNS updating software is running and working correctly.
+
+# Using Dreamhost
+Cost: About $5 per month; Limitations: None really; Extra Requirements: SFTP or FTP software, and an SSH client like PuTTY on windows, or the Terminal on Linuxes and Mac OS.
+
+Dreamhost have some really cheap hosting plans, and are quite easy to use. They include support for Rack on their shared hosting plans, and are fairly reliable and fast.
+
+Enable the "Passenger (Ruby/Python apps only):" option in a domain's settings, from the Manage Domains page within the Dreamhost Panel. Ensure the "Shell account - allows SFTP/FTP plus ssh access." option is enabled on your main user, from the Manage Users page. Use your SSH software to login, and if you haven't already, set up rubygems. Once that's done, it's time to install stuff!
+
+```
+gem install camping-omnibus
+```
+
+Install any other gems you might need for your app, then use your SFTP or FTP software to upload the file to the folder labeled with your domain's name. Lastly, you'll need to add a few things:
+
+A folder called 'tmp', containing a file called 'restart.txt', which you'll need to change whenever you need to make Dreamhost reload your app's source code (while you're trying things out, you can change this filename to 'always_restart.txt' to reload the app with each request).
+
+A file called config.ru, containing something like:
+
+```ruby
+require 'rubygems'
+ENV['GEM_PATH'] = File.join(File.dirname(__FILE__), '..', '.gems') if File.exist?('/dh')
+Gem.clear_paths
+require 'rack'
+require 'blog.rb'
+
+use Rack::ShowExceptions # optional, but helpful if there's any errors
+
+Blog.create if Blog.respond_to? :create
+run Blog
+```
+
+Make sure it's all uploaded, and your app should be online! Yay!
+
+# Using Heroku
+Cost: None for small apps; Limitations: Cannot change files in the filesystem, must use database; Extra Requirements: Need to install and use git to upload your app to the Heroku servers.
+
+Someone should really add stuff to this section. For now, see How to run Camping 2.0 apps on Heroku or Heroku's own guide for Rack-based apps (scroll down for Camping).
+
+# Using Google App Engine
+Cost: None for small apps; Limitations: Cannot change files in the filesystem, must use the google database; Extra Requirements: ???.
+
+Someone should also add information to this section. It's possible using jRuby somehow. I imagine this guide would help a lot!
+
+# Using a CGI Webhost
+Firstly, make sure your webhost can run ruby apps. Most can, thankfully. If you have shell access, you can check by entering 'which ruby' and seeing if it finds anything. Unfortunately, different webhosts work differently, so we can't provide specific instructions for installing rubygems on your webhost. If all else fails, you can extract the files from the lib folder within each gem, put the files in a folder, and add the big folder to your load path. Once you've done this, you'll just need to make sure your camping app file starts with:
+
+```ruby
+#!/usr/bin/ruby
+```
+
+And then either the simple postamble, or the complex postamble:
+
+```ruby
+# Plug it in to CGI
+Rackup::Handler::CGI.run(Blog)) if __FILE__ == $0
+```
+
+Then upload it to your server, and change the file's permissions to have all the executable bits set. You should now be able to visit the file using your web browser (for example, http://example.com/blog.rb). In fact, you don't even need the .rb. the #!/usr/bin/ruby line lets your server know what kind of file it is. :)
+
+
+# Using a Rack Compatible Web Host
+
+Follow your Webhost's instructions, and in the config.ru file, add a little something like this:
+
+```ruby
+... require 'blog' run Blog end
+```
+
+To set up Passenger and Rack for really easy deployment under Apache or Nginx see the screencasts on the Passenger site. If you have (e.g.) Apache on your computer, this is also good for local testing too.
+
+You can also use Rack::URLMap to plug a whole bunch of different apps in to one folder. A camping app here, a rails project there, a sinatra doodad over there in the corner messing up the whole global namespace. The possibilities are severely limited!
+
+# And Also Some Luck
+We wish you good luck! Publishing your app to a server can be an annoying experience the first time you do it. Often little bugs will appear you never noticed before on your computer, or things just might not work for mysterious reasons. Stick to it, and don't be afraid to ask for help from those more battle hardened.

data/book/09_upgrade_notes.md

@@ -0,0 +1,96 @@
+# Upgrade notes
+This document includes everything needed in order to upgrade your applications. If you’re looking for all the new features in a version, please have a look at the CHANGELOG in the Camping source.
+
+# From 2.0 to 2.1
+
+## Options
+In Camping 2.1 there is now a built-in way to store options and settings. If you use cookie session, it means that you’ll now have to change to:
+```ruby
+module Nuts
+  set :secret, "Very secret text, which no-one else should know!"
+  include Camping::Session
+end
+```
+
+# From 1.5 to 2.0
+
+## Rack
+The biggest change in 2.0 is that it now uses Rack internally. This means that you’ll now have to deploy Camping differently, but hopefully more easily too. Now every Camping application is also a Rack application, so simply check out the documentation to the server of your choice.
+
+## Require 'camping/db'
+In earlier versions of Camping, you loaded database support by:
+```ruby
+require 'camping/db'
+```
+
+Actually, this loaded a very thin layer on top of ActiveRecord, and in the future we want to experiment with other libraries. Therefore you should now simply remove the line, and instead just inherit from Base right away. This also means you’ll have to place your migrations after the models.
+
+We also encourage you to use `Model.table_name` instead of `:appname_model`, just to make sure it’s named correctly.
+
+```ruby
+## Don't require anything:
+# require 'camping/db'
+
+module Nuts::Models
+  ## Just inherit Base:
+  class Page < Base; end
+
+  ## Migrations have to come *after* the models:
+  class CreateTheBasics < V 0.1
+    def self.up
+      create_table Page.table_name do |t|
+        ...
+      end
+    end
+
+    def self.down
+      drop_table Page.table_name
+    end
+  end
+end
+```
+
+
+## Cookie Sessions
+Camping 2.0 now uses a cookie-based session system, which means you no longer need a database in order to use sessions. The disadvantage of this is that you are restricted to only around 4k of data. See below for the changes required, and see Camping::Session more details.
+```ruby
+module Nuts
+  ## Include Camping::Session as before:
+  include Camping::Session
+
+  ## But also define a secret:
+  secret "Very secret text, which no-one else should know!"
+end
+
+def Nuts.create
+  ## And remove the following line:
+  # Camping::Models::Session.create_schema
+end
+```
+
+
+## Error Handling
+Camping now uses three methods in order to handle errors. These replaces the old classes NotFound and ServerError.
+
+r404 is called when a route can’t be found.
+r501 is called when a route is found, but doesn’t respond to the method.
+r500 is called when an error happens.
+You can override these in your application:
+
+```ruby
+module Nuts
+  def r404(path)
+    "Sorry, but I can't find #{path}."
+  end
+
+  def r501(method)
+    "Sorry, but I can't respond to #{method}."
+  end
+
+  def r500(klass, method, ex)
+    "Sorry, but #{klass}##{method} failed with #{ex}."
+  end
+end
+```
+
+It should be noted that this might change in the future.

data/book/10_middleware.md

@@ -0,0 +1,69 @@
+Middleware in Camping is just Rack Middleware, and if you're familiar with Rack middleware then you'll be right at home. I'm going to assume that you have no idea what Rack or Rack middleware *is*, Let's learn about it.
+
+# The HTTP Request
+
+The web works in a request -> response pattern. When we *GO* to a webpage our browser is making a *request* to a web server. That request is processed and a *response* is sent. We have already covered how a response is mapped to our ruby code through controllers in Chapter 3. Those responses could be any of a number of things, HTML, an image, JSON, CSS. Web servers are pretty capable. When using Camping you'll generally respond with HTML, CSS, or Javascript, maybe some images, usually a bit of everything.
+
+As that request passes through your application you may need to make some decisions about it. Does the request try to get something with restricted access? Is it a request to a dynamic or cached file? Whatever it is we can write some Ruby code to make some decisions about that request before passing it along to Camping's router. That's what Middleware is for.
+
+Middleware is Rack based and follows Rack Middleware conventions. Write a class, name it whatever you want but it must have an `#initialize` and a `#call` method.
+
+```ruby
+class MyMiddleware
+  def initialize(app)
+    @app = app
+  end
+  def call(env)
+    status, headers, body = @app.call(env)
+    # Do something to status, headers, and body here...
+    [status, headers, body] # return an array of the status, headers, body.
+  end
+end
+```
+
+The `#initialize` method must store a reference to an `app` object that is passed in as a parameter. The `#call` method accepts an environment parameter that we call `env` and returns an array with 3 values: `status`, `headers`, and `body`.
+
+Now, when I first saw this I was confused, why do we immediately call `Call` on the app? Each Rack app receives an array to represent the environment, and then returns that same array at the end. It's just passing along the status, headers, and body of our request/response object. There could be a lot of middleware all chained along. In fact, the `app` provided in the initialize method probably isn't the app at all, but some other middleware. Calling the app with the `env` data, then making our own decisions on the `status`, `headers`, and `body`, is how we actually chain the middleware together.
+
+Calling @app sets up each middleware in the middleware chain. It's like taking a break in the middle of washing the dishes, to take out the trash. If you have a lot of middleware it's like:
+* start washing dishes.
+* start taking out trash.
+* start sweeping the floor.
+* finish sweeping the floor.
+* finish taking out the trash.
+* finish washing the dishes.
+
+Sometimes middleware accepts settings or a block, to get your own middleware to do that write it like this:
+
+```ruby
+class MyMiddleware
+  def initialize(app, *a, &block)
+    @app = app
+    a.each { |setting|
+      # do something with each setting
+    }
+    block.call()
+  end
+  # ... call and stuff ...
+end
+```
+
+Execute implicitly passed blocks with yield:
+
+```ruby
+class MyOtherMiddleware
+  def initialize(app, *a) # &block can be omitted, because it's implicitly passed
+    @app = app
+    a.each { |setting|
+      # do something with each setting
+    }
+    yield # calls implicitly passed block
+  end
+end
+```
+
+Good Rack Middleware shouldn't know if you're running a Camping app, or a Sinatra app, or a Rails app. Keep it framework agnostic. The Rack specification is pretty great at keeping that up.
+
+### notes:
+* really good railscast about it that's like... 13 years old: http://railscasts.com/episodes/151-rack-middleware?autoplay=true
+* An extremely old article about it: https://web.archive.org/web/20150105094611/https://www.amberbit.com/blog/2011/07/13/introduction-to-rack-middleware/

data/book/11_gear.md

@@ -0,0 +1,50 @@
+# Pack Your Gear
+Camping provides a way to include and expand Camping without messing with it's innards too much, we call these plugins gear.
+
+To use gear you need to *pack* it into camping:
+
+```ruby
+Camping.goes :Blog
+
+module Blog
+  pack Camping::Gear::CSRF
+end
+
+# or
+
+Blog.pack Camping::Gear::CSRF
+```
+
+Define your gear by opening a module:
+```ruby
+module Royalty
+  def queens
+    @queens ||= [ "Beyonce", "Niki", "Doja"]
+  end
+end
+```
+
+Gear define methods and helpers that are included in your app. Define a `ClassMethods` module to have class methods included:
+```ruby
+module Royalty
+  module ClassMethods
+    def secret_sauce
+      @_secret_sauce ||= SecureRandom.base64(32)
+    end
+  end
+  # /...
+end
+```
+
+You can also supply a setup callback method that runs after your gear is packed:
+```ruby
+module Royalty
+  # Run a setup routine with this Gear.
+  def self.setup(app)
+    @app = app
+    @app.set :saucy_secret, "top_secret_sauce"
+  end
+end
+```
+
+We'll be adding some really great gear soon. In the meantime, try making your own gear.

data/examples/blog.rb

@@ -14,14 +14,14 @@ module Blog
   module Models
     class Post < Base
       belongs_to :user
-      
+
       before_save do |record|
         cloth = RedCloth.new(record.body)
         cloth.hard_breaks = false
         record.html_body = cloth.to_html
       end
     end
-    
+
     class Comment < Base; belongs_to :user; end
     class User < Base; end
 
@@ -31,7 +31,7 @@ module Blog
           t.integer :user_id,          :null => false
           t.string  :title,            :limit => 255
           t.text    :body, :html_body
-          t.timestamps 
+          t.timestamps
         end
         create_table :blog_users, :force => true do |t|
           t.string  :username, :password
@@ -44,7 +44,7 @@ module Blog
         end
         User.create :username => 'admin', :password => 'camping'
       end
-      
+
       def self.down
         drop_table :blog_posts
         drop_table :blog_users
@@ -67,7 +67,7 @@ module Blog
         @post = Post.new
         render :add
       end
-      
+
       def post
         require_login!
         post = Post.create(:title => input.post_title, :body => input.post_body,
@@ -77,7 +77,7 @@ module Blog
     end
 
     class PostN
-      def get(post_id) 
+      def get(post_id)
         @post = Post.find(post_id)
         render :view
       end
@@ -93,8 +93,8 @@ module Blog
       def post(post_id)
         require_login!
         @post = Post.find(post_id)
-        @post.update_attributes :title => input.post_title, :body => input.post_body
-        redirect PostN, @post  
+        @post.update :title => input.post_title, :body => input.post_body
+        redirect PostN, @post
       end
     end
 
@@ -102,7 +102,7 @@ module Blog
       def get
         render :login
       end
-      
+
       def post
         @user = User.find_by_username_and_password(input.username, input.password)
 
@@ -112,7 +112,7 @@ module Blog
         else
           @info = 'Wrong username or password.'
         end
-        
+
         render :login
       end
     end
@@ -128,17 +128,17 @@ module Blog
       STYLE = File.read(__FILE__).gsub(/.*__END__/m, '')
 
       def get
-        @headers['Content-Type'] = 'text/css; charset=utf-8'
+        @headers['content-type'] = 'text/css; charset=utf-8'
         STYLE
       end
     end
   end
-  
+
   module Helpers
     def logged_in?
       !!@state.user_id
     end
-    
+
     def require_login!
       unless logged_in?
         redirect Controllers::Login
@@ -152,18 +152,18 @@ module Blog
       html do
         head do
           title 'My Blog'
-          link :rel => 'stylesheet', :type => 'text/css', 
+          link :rel => 'stylesheet', :type => 'text/css',
           :href => '/styles.css', :media => 'screen'
         end
         body do
           h1 { a 'My Blog', :href => R(Index) }
-          
+
           div.wrapper! do
-            text yield
+            self << yield
           end
-          
+
           hr
-          
+
           p.footer! do
             if logged_in?
               _admin_menu
@@ -171,7 +171,7 @@ module Blog
               a 'Login', :href => R(Login)
               text ' to the adminpanel'
             end
-            text ' &ndash; Powered by '
+            text! ' &ndash; Powered by '
             a 'Camping', :href => 'http://camping.rubyforge.org/'
           end
         end
@@ -196,10 +196,10 @@ module Blog
     def login
       h2 'Login'
       p.info @info if @info
-      
+
       form :action => R(Login), :method => 'post' do
         input :name => 'to', :type => 'hidden', :value => @to if @to
-        
+
         label 'Username', :for => 'username'
         input :name => 'username', :id => 'username', :type => 'text'
 
@@ -224,21 +224,21 @@ module Blog
 
     # partials
     def _admin_menu
-      text [['Log out', R(Logout)], ['New', R(PostNew)]].map { |name, to|
-        capture { a name, :href => to}
+      text! [['Log out', R(Logout)], ['New', R(PostNew)]].map { |name, to|
+        mab { a name, :href => to}
       }.join(' &ndash; ')
     end
 
     def _post(post)
       h2 { a post.title, :href => R(PostN, post) }
       p.info do
-        text "Written by <strong>#{post.user.username}</strong> "
+        text! "Written by <strong>#{post.user.username}</strong> "
         text post.updated_at.strftime('%B %M, %Y @ %H:%M ')
         _post_menu(post)
       end
-      text post.html_body
+      text! post.html_body
     end
-    
+
     def _post_menu(post)
       if logged_in?
         a '(edit)', :href => R(Edit, post)
@@ -248,7 +248,7 @@ module Blog
     def _form(post, opts)
       form({:method => 'post'}.merge(opts)) do
         label 'Title', :for => 'post_title'
-        input :name => 'post_title', :id => 'post_title', :type => 'text', 
+        input :name => 'post_title', :id => 'post_title', :type => 'text',
               :value => post.title
 
         label 'Body', :for => 'post_body'
@@ -281,12 +281,12 @@ h1, h2, h3, h4 {
   font-weight: normal;
 }
 
-h1 {  
+h1 {
   background-color: #EEE;
   border-bottom: 5px solid #6F812D;
-  outline: 5px solid #9CB441;       
+  outline: 5px solid #9CB441;
   font-weight: normal;
-  font-size: 3em;  
+  font-size: 3em;
   padding: 0.5em 0;
   text-align: center;
 }
@@ -301,7 +301,7 @@ h1 a:hover { color: #143D55; text-decoration: underline }
 h2 a { color: #287AA9; text-decoration: none }
 h2 a:hover { color: #287AA9; text-decoration: underline }
 
-#wrapper { 
+#wrapper {
   margin: 3em auto;
   width: 700px;
 }
@@ -333,29 +333,29 @@ a:hover {
 
 hr {
   border-width: 5px 0;
-  border-style: solid;     
+  border-style: solid;
   border-color: #9CB441;
   border-bottom-color: #6F812D;
-  height: 0;   
+  height: 0;
 }
 
-p#footer {    
+p#footer {
   font-size: 0.9em;
-  margin: 0;      
+  margin: 0;
   padding: 1em;
   text-align: center;
 }
 
-label {  
+label {
   display: block;
   width: 100%;
 }
 
 input, textarea {
-  padding: 5px;     
+  padding: 5px;
   margin-bottom: 1em;
   margin-right: 490px;
-  width: 200px;  
+  width: 200px;
 }
 
 input.submit {

data/lib/camping/ar.rb

@@ -9,13 +9,28 @@ end
 $AR_EXTRAS = %{
   Base = ActiveRecord::Base unless const_defined? :Base
 
+  class ActiveRecordCloser
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      @app.call(env)
+    ensure
+      conn = ActiveRecord::Base.connection
+      conn.close if conn.respond_to?(:close)
+    end
+  end
+
+  Camping.use ActiveRecordCloser
+
   class SchemaInfo < Base
   end
 
   def self.V(n)
     @final = [n, @final.to_f].max
     m = (@migrations ||= [])
-    Class.new(ActiveRecord::Migration) do
+    Class.new(ActiveRecord::Migration[6.1]) do
       meta_def(:version) { n }
       meta_def(:inherited) { |k| m << k }
     end
@@ -33,13 +48,13 @@ $AR_EXTRAS = %{
         end
       end
 
-      si = SchemaInfo.find(:first) || SchemaInfo.new(:version => opts[:assume])
+      si = SchemaInfo.first || SchemaInfo.new(:version => opts[:assume])
       if si.version < opts[:version]
         @migrations.sort_by { |m| m.version }.each do |k|
           k.migrate(:up) if si.version < k.version and k.version <= opts[:version]
           k.migrate(:down) if si.version > k.version and k.version > opts[:version]
         end
-        si.update_attributes(:version => opts[:version])
+        si.update(:version => opts[:version])
       end
     end
   end
@@ -69,7 +84,7 @@ module Camping
     module_eval $AR_EXTRAS
   end
 end
-Camping::S.sub! /autoload\s*:Base\s*,\s*['"]camping\/ar['"]/, $AR_EXTRAS
+Camping::S.sub!(/autoload\s*:Base\s*,\s*['"]camping\/ar['"]/, $AR_EXTRAS)
 Camping::Apps.each do |c|
-  c::Models.module_eval $AR_EXTRAS
+  c::Models.module_eval $AR_EXTRAS.gsub('Camping', c.to_s)
 end