Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 153 lines (110 sloc) 5.627 kb
d850fca Blake Carlson Updated the README and added an rdoc task.
authored
1 = Rack::GridFS
2
3 Rack:GridFS is a Rack middleware for creating HTTP endpoints for files
4 stored in MongoDB's GridFS. You can configure a prefix string which
643251b Ches Martin Refactoring, tests, documentation
ches authored
5 will be used to match the path of a request, and further look up GridFS
6 files based on either their +ObjectId+ or +filename+ field.
d850fca Blake Carlson Updated the README and added an rdoc task.
authored
7
8 For example,
9
a2d0e5e Blake Carlson Updated the readme for mongo 0.20.1 compatibility changes.
authored
10 GET '/gridfs/someobjectid'
d902472 Ches Martin Whitespace
ches authored
11
a2d0e5e Blake Carlson Updated the readme for mongo 0.20.1 compatibility changes.
authored
12 If the prefix is "gridfs", then the id will be be "someobjectid".
d850fca Blake Carlson Updated the README and added an rdoc task.
authored
13
2841fb0 Ben Marini Bring documentation up to date
bmarini authored
14 You can also use Rack::GridFS::Endpoint as a rack endpoint if you want to
15 handle routing another way
16
a2d0e5e Blake Carlson Updated the readme for mongo 0.20.1 compatibility changes.
authored
17 == Mongo Driver Compatibility Notes
d850fca Blake Carlson Updated the README and added an rdoc task.
authored
18
2841fb0 Ben Marini Bring documentation up to date
bmarini authored
19 This version is currently based on mongo-1.2+. As there were significant changes
dab436d Ches Martin BSON::ObjectId
ches authored
20 to the GridFS API prior to v1.0, you may have luck with the git-tagged version
21 0.2.0 of this library with earlier versions of the driver.
d850fca Blake Carlson Updated the README and added an rdoc task.
authored
22
b4d8434 Blake Carlson Added gem installation instructions to README.
authored
23 == Installation
24
dab436d Ches Martin BSON::ObjectId
ches authored
25 gem install rack-gridfs
b4d8434 Blake Carlson Added gem installation instructions to README.
authored
26
2841fb0 Ben Marini Bring documentation up to date
bmarini authored
27 == Features
28 - Use as rack middleware or mount as a rack endpoint
29 - File lookup using a path or object id
30 - Chunked transfer encoding, keeps memory usage low
31 - Content-Type header set using 'mime-types' gem
32 - Last-Modified and Etag headers set automatically for conditional get support
33 - Cache-Control header support
34 - High availability when using replication sets
35
d850fca Blake Carlson Updated the README and added an rdoc task.
authored
36 == Usage
37
b4d8434 Blake Carlson Added gem installation instructions to README.
authored
38 require 'rack/gridfs'
643251b Ches Martin Refactoring, tests, documentation
ches authored
39 use Rack::GridFS, :prefix => 'gridfs', :hostname => 'localhost', :port => 27017, :database => 'test'
b4d8434 Blake Carlson Added gem installation instructions to README.
authored
40
643251b Ches Martin Refactoring, tests, documentation
ches authored
41 Options:
42 - +prefix+: a string used to match against incoming paths and route to through
43 the middleware. Default 'gridfs'.
44 - +lookup+: whether to look up a file based on <tt>:id</tt> or <tt>:path</tt>
45 (example below). Default is <tt>:id</tt>.
7bc6b7a Ches Martin Document new fs_name option, changelog
ches authored
46 - +fs_name+: collection name for the file system, if not using the Mongo driver
47 default ("fs").
d850fca Blake Carlson Updated the README and added an rdoc task.
authored
48
643251b Ches Martin Refactoring, tests, documentation
ches authored
49 You must also specify MongoDB database details:
50 - +hostname+: the hostname/IP where the MongoDB server is running. Default 'localhost'.
51 - +port+: the port of the MongoDB server. Default 27017.
52 - +database+: the name of the MongoDB database to connect to.
53 - +username+ and +password+: if you need to authenticate to MongoDB.
d850fca Blake Carlson Updated the README and added an rdoc task.
authored
54
2841fb0 Ben Marini Bring documentation up to date
bmarini authored
55 Alternatively you can pass in a <tt>Mongo::DB</tt> instance instead:
56 - +db+: MongoMapper.database, or Mongoid.database for example.
57
643251b Ches Martin Refactoring, tests, documentation
ches authored
58 === Simple Sinatra Example
a2d0e5e Blake Carlson Updated the readme for mongo 0.20.1 compatibility changes.
authored
59
d850fca Blake Carlson Updated the README and added an rdoc task.
authored
60 require 'rubygems'
61 require 'sinatra'
62
63 require 'rack/gridfs'
643251b Ches Martin Refactoring, tests, documentation
ches authored
64 use Rack::GridFS, :database => 'test', :prefix => 'gridfs'
d850fca Blake Carlson Updated the README and added an rdoc task.
authored
65
66 get /.*/ do
a2d0e5e Blake Carlson Updated the readme for mongo 0.20.1 compatibility changes.
authored
67 "The URL did not match a file in GridFS."
d850fca Blake Carlson Updated the README and added an rdoc task.
authored
68 end
69
2841fb0 Ben Marini Bring documentation up to date
bmarini authored
70 === Usage with Rails 2
643251b Ches Martin Refactoring, tests, documentation
ches authored
71
72 To use <tt>Rack::GridFS</tt> in a Rails application, add it as middleware in
73 <tt>application.rb</tt> or <tt>config/environments/*</tt>with something like this:
74
75 config.middleware.insert_after Rack::Runtime, Rack::GridFS,
76 :prefix => 'uploads', :database => "my_app_#{Rails.env}"
77
78 Run <tt>rake middleware</tt> to decide for yourself where to best place it in
79 the middleware stack for your app using {the Rails convenience methods}[http://guides.rubyonrails.org/rails_on_rack.html#configuring-middleware-stack],
80 taking into consideration that it can probably be near the top since it simply
81 returns a "static" file or a 404.
82
2841fb0 Ben Marini Bring documentation up to date
bmarini authored
83 === Usage with Rails 3
84
a6b76c5 Ches Martin Note why you might choose endpoint or middleware config
ches authored
85 To use in Rails 3, you can insert into the middleware stack as above, or mount
86 the app directly in your routes (recommended). In <tt>config/routes.rb</tt>:
2841fb0 Ben Marini Bring documentation up to date
bmarini authored
87
7109e06 Ches Martin Fix Rack::GridFS::Endpoint instantiated directly having no mapper
ches authored
88 mount Rack::GridFS::Endpoint.new(:db => Mongoid.database), :at => "gridfs"
2841fb0 Ben Marini Bring documentation up to date
bmarini authored
89
a6b76c5 Ches Martin Note why you might choose endpoint or middleware config
ches authored
90 This allows for much more straightforward and sensible configuration, if you do
91 not require other middleware in front of GridFS (Rack-based authorization, for
92 instance).
93
643251b Ches Martin Refactoring, tests, documentation
ches authored
94 === Path (filename) Lookup
95
96 The <tt>:lookup => :path</tt> option causes files to be looked up from the GridFS
97 store based on their +filename+ field (which can be a full file path) rather than
98 +ObjectId+ (requests still need to match the +prefix+ you've set). This allows
99 you to find files based on essentially arbitrary URLs such as:
100
101 GET '/prefix/media/images/jane_avatar.jpg'
102
103 How filenames are set is specific to your application. We'll look at an example
104 with Carrierwave below.
105
106 *NOTE*: The Mongo Ruby driver will try to create an index on the +filename+
107 field for you automatically, but if you are using filename lookup you'll want to
108 double-check that it is created appropriately (on slaves only if you have a
109 master-slave architecture, etc.).
110
111 === Carrierwave Example
112
113 Path lookup works well for usage with Carrierwave[https://github.com/jnicklas/carrierwave].
114 As a minimal example with Mongoid:
115
116 # config/initializers/carrierwave.rb
117 CarrierWave.configure do |config|
118 config.storage = :grid_fs
119 config.grid_fs_connection = Mongoid.database
120 config.grid_fs_access_url = "/uploads"
121 end
122
123 # app/uploaders/avatar_uploader.rb
124 class AvatarUploader < CarrierWave::Uploader::Base
125 # (Virtual) path where uploaded files will be stored, appended to the
126 # gridfs_access_url by methods used with view helpers
127 def store_dir
128 "#{model.class.to_s.underscore}/#{mounted_as}/#{model.id}"
129 end
130 end
131
132 # app/models/user.rb
133 class User
134 include Mongoid::Document
135 mount_uploader :avatar, AvatarUploader
136 end
137
138 # app/views/user/show.html.erb
139 <%= image_tag(@user.avatar.url) if @user.avatar? %>
140
141 This will result in URL paths like <tt>/uploads/user/avatar/4d250d04a8f41c0a31000006/original_filename.jpg</tt>
142 being generated for the view helpers, and Carrierwave will store
143 <tt>user/avatar/4d250d04a8f41c0a31000006/original_filename.jpg</tt> as the
144 +filename+ in GridFS. Thus, you can configure <tt>Rack::GridFS</tt> to serve
145 these files as such:
146
147 config.middleware.insert_after Rack::Runtime, Rack::GridFS,
148 :prefix => 'uploads', :lookup => :path, :database => "my_app_#{Rails.env}"
149
d850fca Blake Carlson Updated the README and added an rdoc task.
authored
150 == Copyright
151
7e1b075 Ches Martin Copyright dates
ches authored
152 Copyright (c) 2010-2011 Blake Carlson. See LICENSE for details.
Something went wrong with that request. Please try again.