s33r 0.3.1 → 0.4

data/examples/cli/acl_x.rb

@@ -0,0 +1,41 @@
+# Example of how to manipulate ACLs (see s3_acl.rb or rdoc for all ACL classes)
+
+require File.join(File.dirname(__FILE__), '../../lib/s33r')
+include S33r
+include S33r::S3ACL
+
+# initialise the client from a config file 
+# (see s3.yaml in examples directory)
+c = Client.init('/home/ell/.s33r')
+
+# bucket whose ACL we're going to manipulate
+bucket = 'es-test'
+
+# get the ACL for the bucket
+acl = c.get_acl(bucket)
+
+# add a new grant to the ACL (allow all users read access)
+acl.add_grant(Grant.for_group(:all_users, :read))
+
+# remove a grant from the ACL;
+# note that s33r is able to compare existing grants in
+# an ACL with newly-minted ones
+acl.remove_grant(Grant.for_group(:authenticated_users, :read))
+
+# put the ACL back
+c.set_acl(acl, bucket)
+
+# get the ACL for a resource inside the bucket
+# and make it readable by a specific Amazon customer
+resource = 'test'
+
+# NB this method raises an error if the resource doesn't exist
+acl = c.get_acl(bucket, resource)
+
+# the email address you set here needs to be a valid Amazon customer
+acl.add_grant(Grant.for_amazon_customer('elliot@example.com', :read))
+p c.set_acl(acl, bucket, resource)
+
+# short-hand for making a resource public
+# c.make_public(bucket)
+# c.make_public(bucket, resource)

data/examples/cli/logging_x.rb

@@ -0,0 +1,20 @@
+# Example of how to set up logging on a bucket or resource.
+
+require File.join(File.dirname(__FILE__), '../../lib/s33r')
+include S33r
+
+# initialise the client from a config file 
+# (see s3.yaml in examples directory)
+c = Client.init('/home/ell/.s33r')
+
+# Make a logging destination
+# This sets the required ACLs on a bucket to make it writeable by the
+# logging processes.
+c.enable_log_target('my-logging-bucket')
+
+# Set up logging for a bucket.
+c.enable_logging('es-test', 'my-logging-bucket')
+
+# Set up logging for a bucket with a custom log prefix.
+# (Default prefix is the name of the bucket which has logging enabled + "'")
+c.enable_logging('es-test2', 'my-logging-bucket', :prefix => 'special-logs-')

data/{bin → examples/cli}/s3cli.rb

@@ -1,9 +1,11 @@
 # SIMPLE COMMAND LINE S3 CLIENT
 # You need an Amazon S3 account to use this: get one at http://aws.amazon.com/
 #
-# Create a config. file called based on the example in test/files/namedbucket_config.yml;
-# then change the config_file setting below to set the path to your config. file.
-# You will be prompted to create a bucket if your setting for bucket in the config.
+# Create a config. file called based on the example in examples/s3.yaml -
+# you need to set your keys and the name of the default_bucket to use for storing files;
+# then change the config_file line below to set the path to your config. file.
+# 
+# NB you will be prompted to create a bucket if your setting for bucket in the config.
 # file is blank.
 #
 # Note that this script doesn't give you any means of deleting anything; you will
@@ -15,17 +17,19 @@
 # based on filename supplied (including path)
 # to_email: email address to send to (optional)
 
+# set to the path to your s3.yaml file
+config_file = '/home/ell/.s33r'
+
 require 'yaml'
 require 'net/smtp'
 require 'time'
 require 'parsedate'
 
-require File.join(File.dirname(__FILE__), '../lib/s33r')
+# load the S33r libraries
+require File.join(File.dirname(__FILE__), '..', '..', 'lib', 's33r')
 
 filename = ARGV[0]
 to_email = ARGV[1]
-# set to the path to your config. file
-config_file = '/home/ell/.s33r'
 
 # load config. file
 access_key, secret_key, options, custom = S33r::Client.load_config(config_file)
@@ -36,23 +40,12 @@ bucket = options[:default_bucket]
 puts "Using bucket: #{bucket}"
 
 # email addresses
-to_email = custom[:to_email]
-from_email = custom[:from_email]
+to_email = options[:to_email]
+from_email = options[:from_email]
 
 # expires can be a date/time string or 'forever';
 # if not set, defaults to 15 minutes
-expires = options[:default_expires]
-base_expires = Time.now.to_i
-if 'forever' == expires
-  # 20 years (same as forever in computer terms)
-  expires = base_expires + (60 * 60 * 24 * 365.25 * 20).to_i
-elsif expires.is_a?(String)
-  datetime_parts = ParseDate.parsedate(expires)
-  expires = Time.gm(*datetime_parts).to_i
-elsif !expires
-  # default to 15 minutes from now if not set
-  expires = base_expires + (15*60)
-end
+expires = S33r.parse_expiry(options[:default_expires])
 
 # check for bucket
 if !bucket

data/examples/fores33r/README

@@ -0,0 +1,183 @@
+== Welcome to Rails
+
+Rails is a web-application and persistence framework that includes everything
+needed to create database-backed web-applications according to the
+Model-View-Control pattern of separation. This pattern splits the view (also
+called the presentation) into "dumb" templates that are primarily responsible
+for inserting pre-built data in between HTML tags. The model contains the
+"smart" domain objects (such as Account, Product, Person, Post) that holds all
+the business logic and knows how to persist themselves to a database. The
+controller handles the incoming requests (such as Save New Account, Update
+Product, Show Post) by manipulating the model and directing data to the view.
+
+In Rails, the model is handled by what's called an object-relational mapping
+layer entitled Active Record. This layer allows you to present the data from
+database rows as objects and embellish these data objects with business logic
+methods. You can read more about Active Record in 
+link:files/vendor/rails/activerecord/README.html.
+
+The controller and view are handled by the Action Pack, which handles both
+layers by its two parts: Action View and Action Controller. These two layers
+are bundled in a single package due to their heavy interdependence. This is
+unlike the relationship between the Active Record and Action Pack that is much
+more separate. Each of these packages can be used independently outside of
+Rails.  You can read more about Action Pack in 
+link:files/vendor/rails/actionpack/README.html.
+
+
+== Getting started
+
+1. Start the web server: <tt>ruby script/server</tt> (run with --help for options)
+2. Go to http://localhost:3000/ and get "Welcome aboard: You’re riding the Rails!"
+3. Follow the guidelines to start developing your application
+
+
+== Web servers
+
+Rails uses the built-in web server in Ruby called WEBrick by default, so you don't
+have to install or configure anything to play around. 
+
+If you have lighttpd installed, though, it'll be used instead when running script/server.
+It's considerably faster than WEBrick and suited for production use, but requires additional
+installation and currently only works well on OS X/Unix (Windows users are encouraged
+to start with WEBrick). We recommend version 1.4.11 and higher. You can download it from
+http://www.lighttpd.net.
+
+If you want something that's halfway between WEBrick and lighttpd, we heartily recommend
+Mongrel. It's a Ruby-based web server with a C-component (so it requires compilation) that
+also works very well with Windows. See more at http://mongrel.rubyforge.org/.
+
+But of course its also possible to run Rails with the premiere open source web server Apache.
+To get decent performance, though, you'll need to install FastCGI. For Apache 1.3, you want
+to use mod_fastcgi. For Apache 2.0+, you want to use mod_fcgid.
+
+See http://wiki.rubyonrails.com/rails/pages/FastCGI for more information on FastCGI.
+
+== Example for Apache conf
+
+  <VirtualHost *:80>
+    ServerName rails
+    DocumentRoot /path/application/public/
+    ErrorLog /path/application/log/server.log
+  
+    <Directory /path/application/public/>
+      Options ExecCGI FollowSymLinks
+      AllowOverride all
+      Allow from all
+      Order allow,deny
+    </Directory>
+  </VirtualHost>
+
+NOTE: Be sure that CGIs can be executed in that directory as well. So ExecCGI
+should be on and ".cgi" should respond. All requests from 127.0.0.1 go
+through CGI, so no Apache restart is necessary for changes. All other requests
+go through FCGI (or mod_ruby), which requires a restart to show changes.
+
+
+== Debugging Rails
+
+Have "tail -f" commands running on both the server.log, production.log, and
+test.log files. Rails will automatically display debugging and runtime
+information to these files. Debugging info will also be shown in the browser
+on requests from 127.0.0.1.
+
+
+== Breakpoints
+
+Breakpoint support is available through the script/breakpointer client. This
+means that you can break out of execution at any point in the code, investigate
+and change the model, AND then resume execution! Example:
+
+  class WeblogController < ActionController::Base
+    def index
+      @posts = Post.find_all
+      breakpoint "Breaking out from the list"
+    end
+  end
+  
+So the controller will accept the action, run the first line, then present you
+with a IRB prompt in the breakpointer window. Here you can do things like:
+
+Executing breakpoint "Breaking out from the list" at .../webrick_server.rb:16 in 'breakpoint'
+
+  >> @posts.inspect
+  => "[#<Post:0x14a6be8 @attributes={\"title\"=>nil, \"body\"=>nil, \"id\"=>\"1\"}>, 
+       #<Post:0x14a6620 @attributes={\"title\"=>\"Rails you know!\", \"body\"=>\"Only ten..\", \"id\"=>\"2\"}>]"
+  >> @posts.first.title = "hello from a breakpoint"
+  => "hello from a breakpoint"
+
+...and even better is that you can examine how your runtime objects actually work:
+
+  >> f = @posts.first 
+  => #<Post:0x13630c4 @attributes={"title"=>nil, "body"=>nil, "id"=>"1"}>
+  >> f.
+  Display all 152 possibilities? (y or n)
+
+Finally, when you're ready to resume execution, you press CTRL-D
+
+
+== Console
+
+You can interact with the domain model by starting the console through script/console. 
+Here you'll have all parts of the application configured, just like it is when the
+application is running. You can inspect domain models, change values, and save to the
+database. Starting the script without arguments will launch it in the development environment.
+Passing an argument will specify a different environment, like <tt>script/console production</tt>.
+
+To reload your controllers and models after launching the console run <tt>reload!</tt>
+
+
+
+== Description of contents
+
+app
+  Holds all the code that's specific to this particular application.
+
+app/controllers
+  Holds controllers that should be named like weblog_controller.rb for
+  automated URL mapping. All controllers should descend from
+  ActionController::Base.
+
+app/models
+  Holds models that should be named like post.rb.
+  Most models will descend from ActiveRecord::Base.
+  
+app/views
+  Holds the template files for the view that should be named like
+  weblog/index.rhtml for the WeblogController#index action. All views use eRuby
+  syntax. This directory can also be used to keep stylesheets, images, and so on
+  that can be symlinked to public.
+  
+app/helpers
+  Holds view helpers that should be named like weblog_helper.rb.
+
+app/apis
+  Holds API classes for web services.
+
+config
+  Configuration files for the Rails environment, the routing map, the database, and other dependencies.
+
+components
+  Self-contained mini-applications that can bundle together controllers, models, and views.
+
+db
+  Contains the database schema in schema.rb.  db/migrate contains all
+  the sequence of Migrations for your schema.
+
+lib
+  Application specific libraries. Basically, any kind of custom code that doesn't
+  belong under controllers, models, or helpers. This directory is in the load path.
+    
+public
+  The directory available for the web server. Contains subdirectories for images, stylesheets,
+  and javascripts. Also contains the dispatchers and the default HTML files.
+
+script
+  Helper scripts for automation and generation.
+
+test
+  Unit and functional tests along with fixtures.
+
+vendor
+  External libraries that the application depends on. Also includes the plugins subdirectory.
+  This directory is in the load path.

data/examples/fores33r/Rakefile

@@ -0,0 +1,10 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require(File.join(File.dirname(__FILE__), 'config', 'boot'))
+
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+require 'tasks/rails'

data/examples/fores33r/app/controllers/application.rb

@@ -0,0 +1,4 @@
+# Filters added to this controller will be run for all controllers in the application.
+# Likewise, all the methods added will be available for all controllers.
+class ApplicationController < ActionController::Base
+end

data/examples/fores33r/app/controllers/browser_controller.rb

@@ -0,0 +1,68 @@
+class BrowserController < ApplicationController
+  before_filter :get_s3_client
+  
+  def get_s3_client
+    @s3 = S3_CLIENT
+    @default_prefix = S3_OPTIONS[:default_prefix]
+  end
+
+  def index
+    @buckets = @s3.list_buckets
+  end
+  
+  def show_bucket
+    @bucket_name = params[:bucket_name]
+    _, listing = @s3.list_bucket(@bucket_name)
+    @keys = listing.pretty
+  end
+  
+  # NB this doesn't check whether the thing being deleted exists;
+  # and as S3 treats a non-existent resource the same way as a 
+  # just-deleted resource, it's difficult to distinguish the two
+  # (short of checking it's there before trying to delete it)
+  def delete
+    bucket_name = params[:bucket_name]
+    resource_key = params[:resource_key]
+    if resource_key
+      @s3.delete_resource(bucket_name, resource_key)
+      to_url = url_for(:action => 'show_bucket', :bucket_name => bucket_name)
+      notice = "Resource"
+    else
+      @s3.delete_bucket(bucket_name, {}, {:force => true})
+      to_url = url_for(:action => 'index')
+      notice = "Bucket"
+    end
+    
+    notice += " deleted successfully"
+    
+    flash[:notice] = notice
+    redirect_to to_url
+  end
+  
+  def upload
+    file_to_upload = params[:upload][:filename]
+    
+    base_filename = file_to_upload.original_filename
+    file_data = file_to_upload.read
+    content_type = file_to_upload.content_type.chomp
+    bucket_name = params[:upload][:bucket_name]
+    
+    @s3.put_resource(bucket_name, base_filename, file_data, {'Content-Type' => content_type})
+    redirect_to :action => 'show_bucket', :bucket_name => bucket_name
+  end
+  
+  def create_bucket
+    new_bucket_name = params[:bucket][:name]
+    use_prefix = (params[:bucket][:prefix]).to_i
+    if use_prefix
+      new_bucket_name = @default_prefix + '-' + new_bucket_name
+    end
+    
+    if @s3.create_bucket(new_bucket_name)
+      flash[:notice] = "New bucket created successfully"
+    else
+      flash[:notice] = "Could not create bucket - already exists"
+    end
+    redirect_to :action => 'index'
+  end
+end

data/examples/fores33r/app/helpers/application_helper.rb

@@ -0,0 +1,8 @@
+# Methods added to this helper will be available to all templates in the application.
+module ApplicationHelper
+  include S33r
+  
+  def authenticated_url(bucket_name, resource_key)
+    s3_authenticated_url(ACCESS_KEY, SECRET_ACCESS_KEY, bucket_name, resource_key, S3_OPTIONS[:default_expires])
+  end
+end

data/examples/fores33r/app/views/browser/index.rhtml

@@ -0,0 +1,14 @@
+<h2>Buckets</h2>
+
+<% for bucket in @buckets %>
+<p><%= link_to bucket.name, :action => 'show_bucket', 
+:bucket_name => bucket.name %> | <%= link_to 'delete', {:action => 'delete', :bucket_name => bucket.name}, 
+:confirm => 'Are you sure you want to delete this bucket?' %></p>
+<% end %>
+
+<%= start_form_tag :action => 'create_bucket' %>
+<p>Create a new bucket: <%= text_field 'bucket', 'name' %></p>
+<p>Use your default bucket prefix (<strong><%= @default_prefix %></strong>)? 
+<%= check_box_tag 'bucket[prefix]', 1, true %></p>
+<p><%= submit_tag 'Create' %></p>
+<%= end_form_tag %>

data/examples/fores33r/app/views/browser/show_bucket.rhtml

@@ -0,0 +1,14 @@
+<h2>Content of bucket <em><%= @bucket_name %></em></h2>
+
+<% for key in @keys do %>
+<p><%= link_to key, authenticated_url(@bucket_name, key) %>&nbsp;|&nbsp;
+<%= link_to 'delete', {:action => 'delete', :bucket_name => @bucket_name, 
+:resource_key => key}, :confirm => 'Are you sure you want to delete this resource?' %>
+</p>
+<% end %>
+
+<%= start_form_tag({:action => 'upload'}, :multipart => true) %>
+<%= hidden_field 'upload', 'bucket_name', :value => @bucket_name %>
+<p>Upload a file to this bucket: <%= file_field('upload', 'filename') %></p>
+<p><%= submit_tag 'Upload' %></p>
+<%= end_form_tag %>

data/examples/fores33r/app/views/layouts/application.rhtml

@@ -0,0 +1,29 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en_GB" xml:lang="en_GB">
+<head>
+<title>fores33r</title>
+<%= stylesheet_link_tag 'core' %>
+</head>
+<body>
+
+<div id="header">
+<h1>fores33r</h1>
+</div>
+
+<div id="left_pane">
+<p><%= link_to 'Buckets', :controller => 'browser', :action => 'index' %></p>
+</div>
+ 
+<div id="main_pane">
+
+<% if not flash.empty? -%>
+<p id="flash"><%= flash[:notice] %></p>
+<% end -%>
+
+<%= @content_for_layout %>
+</div>
+ 
+ </body>
+</html>