asana2flowdock 1.0.0 → 1.1.0

data/vendor/bundle/ruby/1.9.1/gems/sequel-4.15.0/doc/security.rdoc

@@ -1,370 +0,0 @@
-= Security Considerations with Sequel
-
-When using Sequel, there are some security areas you should be aware of:
-
-* Code Execution
-* SQL Injection
-* Denial of Service
-* Mass Assignment
-* General Parameter Handling
-
-== Code Execution
-
-The most serious security vulnerability you can have in any library is
-a code execution vulnerability.  Sequel should not be vulnerable to this,
-as it never calls eval on a string that is derived from user input.
-However, some Sequel methods used for creating methods via metaprogramming
-could conceivably be abused to do so:
-
-* Sequel::Schema::CreateTableGenerator.add_type_method
-* Sequel::Dataset.def_mutation_method
-* Sequel::Dataset.def_sql_method
-* Sequel::Model::Plugins.def_dataset_methods
-* Sequel.def_adapter_method (private)
-* Sequel::SQL::Expression.to_s_method (private)
-* Sequel::Plugins::HookClassMethods::ClassMethods#add_hook_type
-
-As long as you don't call those with user input, you should not be
-vulnerable to code execution.
-
-== SQL Injection
-
-The primary security concern in SQL database libraries is SQL injection.
-Because Sequel promotes using ruby objects for SQL concepts instead
-of raw SQL, it is less likely to be vulnerable to SQL injection.
-However, because Sequel still makes it easy to use raw SQL, misuse of the
-library can result in SQL injection in your application.
-
-There are basically two kinds of possible SQL injections in Sequel:
-
-* SQL code injections
-* SQL identifier injections
-
-=== SQL Code Injections
-
-==== Full SQL Strings
-
-Some Sequel methods are designed to execute raw SQL, including:
-
-* Sequel::Database#execute
-* Sequel::Database#run
-* Sequel::Database#<<
-* Sequel::Database#[]
-* Sequel::Database#fetch
-* Sequel::Dataset#with_sql
-
-Here are some examples of use:
-
-  DB.run 'SQL'
-  DB << 'SQL'
-  DB.execute 'SQL'
-  DB['SQL'].all
-  DB.fetch('SQL').all
-  DB.dataset.with_sql('SQL').all
-
-If you pass a string to these methods that is derived from user input, you open
-yourself up to SQL injection.  The Sequel::Database#run, Sequel::Database#<<, and
-Sequel::Database#execute methods are not designed to work at all with user input.
-If you must use them with user input, you should escape the user input manually
-via Sequel::Database#literal. Example:
-
-  DB.run "SOME SQL #{DB.literal(params[:user].to_s)}"
-
-With Sequel::Database#[], Sequel::Database#fetch and Sequel::Dataset#with_sql, you should use placeholders,
-in which case Sequel automatically literalizes the input:
-
-  DB['SELECT * FROM foo WHERE bar = ?', params[:user].to_s]
-
-==== Manually Created Literal Strings
-
-Sequel generally treats ruby strings as SQL strings (escaping them correctly), and
-not as raw SQL.  However, you can convert a ruby string to a literal string, and
-Sequel will then treat it as raw SQL.  This is typically done through String#lit
-if the {core_extensions}[rdoc-ref:doc/core_extensions.rdoc] are in use,
-or Sequel.lit[rdoc-ref:Sequel::SQL::Builders#lit] if they are not in use.
-
-  'a'.lit
-  Sequel.lit('a')
-
-Using String#lit or Sequel.lit[rdoc-ref:Sequel::SQL::Builders#lit] to turn a ruby string into a literal string results
-in SQL injection if the string is derived from user input.  With both of these
-methods, the strings can contain placeholders, which you can use to safely include
-user input inside a literal string:
-
-  'a = ?'.lit(params[:user_id].to_s)
-  Sequel.lit('a = ?', params[:user_id].to_s)
-
-Even though they have similar names, note that Sequel::Database#literal operates very differently from
-String#lit or Sequel.lit[rdoc-ref:Sequel::SQL::Builders#lit].
-Sequel::Database#literal is for taking any supported object,
-and getting an SQL representation of that object, while
-String#lit or Sequel.lit[rdoc-ref:Sequel::SQL::Builders#lit] are for treating
-a ruby string as raw SQL.  For example:
-
-  DB.literal(Date.today) # "'2013-03-22'"
-  DB.literal('a') # "'a'"
-  DB.literal(Sequel.lit('a')) # "a"
-  DB.literal(:a => 'a') # "(\"a\" = 'a')"
-  DB.literal(:a => Sequel.lit('a')) # "(\"a\" = a)"
-
-==== SQL Filter Fragments
-
-The most common way to use raw SQL with Sequel is in filters:
-
-  DB[:table].where("name > 'M'")
-
-If a filter method is passed a string as the first argument, it treats the rest of
-the arguments (if any) as placeholders to the string.  So you should never do:
-
-  DB[:table].where("name > #{params[:id].to_s}") # SQL Injection!
-
-Instead, you should use a placeholder:
-
-  DB[:table].where("name > ?", params[:id].to_s) # Safe
- 
-Note that for that type of query, Sequel generally encourages the following form:
-
-  DB[:table].where{|o| o.name > params[:id].to_s} # Safe
-
-Sequel's DSL supports a wide variety of SQL concepts, so it's possible to
-code most applications without ever using raw SQL.
-
-A large number of dataset methods ultimately pass down their arguments to a filter
-method, even some you may not expect, so you should be careful.  At least the
-following methods pass their arguments to a filter method:
-
-* Sequel::Dataset#where
-* Sequel::Dataset#having
-* Sequel::Dataset#filter
-* Sequel::Dataset#exclude
-* Sequel::Dataset#exclude_where
-* Sequel::Dataset#exclude_having
-* Sequel::Dataset#and
-* Sequel::Dataset#or
-* Sequel::Dataset#first
-* Sequel::Dataset#last
-* Sequel::Dataset#[]
-* Sequel::Dataset#[]=
-
-The Model.find[rdoc-ref:Sequel::Model::ClassMethods#find] and Model.find_or_create[rdoc-ref:Sequel::Model::ClassMethods#find_or_create]
-class methods also call down to the filter methods.
-
-==== SQL Fragment passed to Dataset#update
-
-Similar to the filter methods, Sequel::Dataset#update also treats a
-string argument as raw SQL:
-
-  DB[:table].update("column = 1")
-
-So you should not do:
-
-  DB[:table].update("column = #{params[:value].to_s}") # SQL Injection!
-
-Instead, you should do:
-
-  DB[:table].update(:column => params[:value].to_s) # Safe
-
-==== SQL Fragment passed to Dataset#lock_style
-
-The Sequel::Dataset#lock_style method also treats an input string 
-as SQL code. This method should not be called with user input.
-
-==== SQL Type Names
-
-In general, most places where Sequel needs to use an SQL type that should
-be specified by the user, it allows you to use a ruby string, and that
-string is used verbatim as the SQL type.  You should not use user input
-for type strings.
-
-==== SQL Function Names
-
-In most cases, Sequel does not quote SQL function names.  You should not use
-user input for function names.
-
-=== SQL Identifier Injections
-
-Usually, Sequel treats ruby symbols as SQL identifiers, and ruby
-strings as SQL strings.  However, there are some parts of Sequel
-that treat ruby strings as SQL identifiers if an SQL string would
-not make sense in the same context.
-
-For example, Sequel::Database#from and Sequel::Dataset#from will treat a string as
-a table name:
-
-  DB.from('t') # SELECT * FROM "t"
-
-Another place where Sequel treats ruby strings as identifiers are
-the Sequel::Dataset#insert and Sequel::Dataset#update methods:
-
-  DB[:t].update('b'=>1) # UPDATE "t" SET "b" = 1
-  DB[:t].insert('b'=>1) # INSERT INTO "t" ("b") VALUES (1)
-
-Note how the identifier is still quoted in these cases.  Sequel quotes identifiers by default
-on most databases.  However, it does not quote identifiers by default on DB2 and Informix.
-On those databases using an identifier derived from user input can lead to SQL injection.
-Similarly, if you turn off identifier quoting manually on other databases, you open yourself
-up to SQL injection if you use identifiers derived from user input.
-
-When Sequel quotes identifiers, using an identifier derived from user input does not lead to
-SQL injection, since the identifiers are also escaped when quoting.
-Exceptions to this are Oracle (can't escape <tt>"</tt>) and Microsoft Access
-(can't escape <tt>]</tt>).
-
-In general, even if doesn't lead to SQL Injection, you should avoid using identifiers
-derived from user input unless absolutely necessary.
-
-Sequel also allows you to create identifiers using
-Sequel.identifier[rdoc-ref:Sequel::SQL::Builders#identifier] for plain identifiers,
-Sequel.qualify[rdoc-ref:Sequel::SQL::Builders#qualify] for qualified identifiers, and
-Sequel.as[rdoc-ref:Sequel::SQL::Builders#as] for aliased expressions.  So if you
-pass any of those values derived from user input, you are dealing with the same scenario.
-
-Note that the issues with SQL identifiers do not just apply to places where
-strings are used as identifiers, they also apply to all places where Sequel
-uses symbols as identifiers.  However, if you are creating symbols from user input,
-you at least have a denial of service vulnerability, and possibly a more serious
-vulnerability.
-
-== Denial of Service
-
-Sequel converts some strings to symbols.  Because symbols in ruby are not
-garbage collected, if the strings that are converted to symbols are
-derived from user input, you have a denial of service vulnerability due to
-memory exhaustion.
-
-The strings that Sequel converts to symbols are generally not derived
-from user input, so Sequel in general is not vulnerable to this.  However,
-users should be aware of the cases in which Sequel creates symbols, so
-they do not introduce a vulnerability into their application.
-
-=== Column Names/Aliases
-
-Sequel returns SQL result sets as an array of hashes with symbol keys.  The
-keys are derived from the name that the database server gives the column. These
-names are generally static.  For example:
-
-  SELECT column FROM table
-
-The database will generally use "column" as the name in the result set.
-
-If you use an alias:
-
-  SELECT column AS alias FROM table
-
-The database will generally use "alias" as the name in the result set. So
-if you allow the user to control the alias name:
-
-  DB[:table].select(:column.as(params[:alias]))
-
-Then you have a denial of service vulnerability.  In general, such a vulnerability
-is unlikely, because you are probably indexing into the returned hash(es) by name,
-and if an alias was used and you didn't expect it, your application wouldn't work.
-
-=== Database Connection Options
-
-All database connection options are converted to symbols.  For a
-connection URL, the keys are generally fixed, but the scheme is turned
-into a symbol and the query option keys are used as connection option
-keys, so they are converted to symbols as well.  For example:
-
-  postgres://host/database?option1=foo&option2=bar
-
-Will result in :postgres, :option1, and :option2 symbols being created.
-
-Certain option values are also converted to symbols.  In the general case,
-the sql_log_level option value is, but some adapters treat additional
-options similarly.
-
-This is not generally a risk unless you are allowing the user to control
-the connection URLs or are connecting to arbitrary databases at runtime.
-
-== Mass Assignment
-
-Mass assignment is the practice of passing a hash of columns and values
-to a single method, and having multiple column values for a given object set
-based on the content of the hash.
-The security issue here is that mass assignment may allow the user to
-set columns that you didn't intend to allow.
-
-The Model#set[rdoc-ref:Sequel::Model::InstanceMethods#set] and Model#update[rdoc-ref:Sequel::Model::InstanceMethods#update] methods do mass
-assignment.  The default configuration of Sequel::Model allows all model
-columns except for the primary key column(s) to be set via mass assignment.
-
-Example:
-
-  album = Album.new
-  album.set(params[:album]) # Mass Assignment
-
-Both Model.new[rdoc-ref:Sequel::Model::InstanceMethods::new] and Model.create[rdoc-ref:Sequel::Model::ClassMethods#create]
-call Model#set[rdoc-ref:Sequel::Model::InstanceMethods#set] internally, so
-they also allow mass assignment:
-
-  Album.new(params[:album]) # Mass Assignment
-  Album.create(params[:album]) # Mass Assignment
-
-Instead of these methods, it is encouraged to either use the
-Model#set_only[rdoc-ref:Sequel::Model::InstanceMethods#set_only],
-Model#update_only[rdoc-ref:Sequel::Model::InstanceMethods#update_only],
-Model#set_fields[rdoc-ref:Sequel::Model::InstanceMethods#set_fields], or
-Model#update_fields[rdoc-ref:Sequel::Model::InstanceMethods#update_fields]
-methods, which allow you to specify which fields
-to allow on a per-call basis.  This pretty much eliminates the chance that the
-user will be able to set a column you did not intend to allow:
-
-  album.set_only(params[:album], [:name, :copies_sold])
-  album.set_fields(params[:album], [:name, :copies_sold])
-
-You can override the columns to allow by default during mass assignment via
-the Model.set_allowed_columns[rdoc-ref:Sequel::Model::ClassMethods#set_allowed_columns] class method.  This is a good
-practice, though being explicit on a per-call basis is still recommended:
-
-  Album.set_allowed_columns(:name, :copies_sold)
-  Album.create(params[:album]) # Only name and copies_sold set
-
-For more details on the mass assignment methods, see the {Mass Assignment Guide}[rdoc-ref:doc/mass_assignment.rdoc].
-
-== General Parameter Handling
-
-This issue isn't necessarily specific to Sequel, but it is a good general practice.
-If you are using values derived from user input, it is best to be explicit about
-their type.  For example:
-
-  Album.where(:id=>params[:id])
-
-is probably a bad idea.  Assuming you are using a web framework, params\[:id\] could
-be a string, an array, a hash, or nil.
-
-Assuming that +id+ is an integer field, you probably want to do:
-
-  Album.where(:id=>params[:id].to_i)
-
-If you are looking something up by name, you should try to enforce the value to be
-a string:
-
-  Album.where(:name=>params[:name].to_s)
-
-If you are trying to use an IN clause with a list of id values based on input provided
-on a web form:
-
-  Album.where(:id=>params[:ids].to_a.map{|i| i.to_i})
-
-Basically, be as explicit as possible. While there aren't any known security issues
-in Sequel when you do:
-
-  Album.where(:id=>params[:id])
-
-It allows the attacker to choose to do any of the following queries:
-
-  id IS NULL # nil
-  id = '1' # '1'
-  id IN ('1', '2', '3') # ['1', '2', '3']
-  id = ('a' = 'b') # {'a'=>'b'}
-  id = ('a' IN ('a', 'b') AND 'c' = '') # {'a'=>['a', 'b'], 'c'=>''}
-
-While none of those allow for SQL injection, it's possible that they
-might have an issue in your application.  For example, a long array
-or deeply nested hash might cause the database to have to do a lot of
-work that could be avoided.
-
-In general, it's best to let the attacker control as little as possible,
-and explicitly specifying types helps a great deal there.

data/vendor/bundle/ruby/1.9.1/gems/sequel-4.15.0/doc/sharding.rdoc

@@ -1,245 +0,0 @@
-= Read-Only Slaves/Writable Master and Database Sharding
-
-Sequel has support for read only slave databases
-with a writable master database, as well as database sharding (where you can
-pick a server to use for a given dataset).  Support for both
-features is database independent, and should work for all database adapters
-that ship with Sequel.
-
-== The :servers Database option
-
-Sharding and read_only support are both enabled via the :servers database
-option.  Using the :servers database option makes Sequel use a connection pool
-class that supports sharding, and the minimum required to enable sharding
-support is to use the empty hash:
-
-  DB=Sequel.connect('postgres://master_server/database', :servers=>{})
-
-In most cases, you are probably not going to want to use an empty hash.  Keys in the server hash are
-not restricted to type, but the general recommendation is to use a symbol
-unless you have special requirements. Values in the server hash should be
-either hashes or procs that return hashes. These hashes are merged into
-the Database object's default options hash to get the connection options
-for the shard, so you don't need to override all options, just the ones
-that need to be modified.  For example, if you are using the same user,
-password, and database name and just the host is changing, you only need
-a :host entry in each shard's hash.
-
-Note that all servers should have the same schema for all
-tables you are accessing, unless you really know what you are doing.
-
-== Master and Slave Database Configurations
-
-=== Single Read-Only Slave, Single Master
-
-To use a single, read-only slave that handles SELECT queries, the following
-is the simplest configuration:
-
-  DB=Sequel.connect('postgres://master_server/database', \
-    :servers=>{:read_only=>{:host=>'slave_server'}})
-
-This will use the slave_server for SELECT queries and master_server for
-other queries.
-
-=== Multiple Read-Only Slaves, Single Master
-
-Let's say you have 4 slave database servers with names slave_server0,
-slave_server1, slave_server2, and slave_server3.
-
-  DB=Sequel.connect('postgres://master_server/database', \
-    :servers=>{:read_only=>proc{|db| {:host=>db.get_slave_host}}})
-  def DB.get_slave_host
-    @current_host ||= -1
-    "slave_server#{(@current_host+=1)%4}"
-  end
-
-This will use one of the slave servers for SELECT queries and use the
-master_server for other queries.  It's also possible to pick a random host
-instead of using the round robin approach presented above, but that can result
-in less optimal resource usage.
-
-=== Multiple Read-Only Slaves, Multiple Masters
-
-This involves the same basic idea as the multiple slaves, single master, but
-it shows that the master database is named :default.  So for 4 masters and
-4 slaves:
-
-  DB=Sequel.connect('postgres://master_server/database', \
-    :servers=>{:read_only=>proc{|db| {:host=>db.get_slave_host}}, \
-      :default=>proc{|db| {:host=>db.get_master_host}}})
-  def DB.get_slave_host
-    @current_slave_host ||= -1
-    "slave_server#{(@current_slave_host+=1)%4}"
-  end
-  def DB.get_master_host
-    @current_master_host ||= -1
-    "master_server#{(@current_master_host+=1)%4}"
-  end
-  
-== Sharding
-
-There is specific support in Sequel for handling master/slave database
-combinations, with the only necessary setup being the database configuration.
-However, since sharding is always going to be implementation dependent, Sequel
-supplies the basic infrastructure, but you have to tell it which server to use
-for each dataset.  Let's assume a simple scenario, a distributed rainbow
-table for SHA-1 hashes, sharding based on the first hex character (for a total
-of 16 shards).  First, you need to configure the database:
-
-  servers = {}
-  (('0'..'9').to_a + ('a'..'f').to_a).each do |hex|
-    servers[hex.to_sym] = {:host=>"hash_host_#{hex}"}
-  end
-  DB=Sequel.connect('postgres://hash_host/hashes', :servers=>servers)
-  
-This configures 17 servers, the 16 shard servers (/hash_host_[0-9a-f]/), and 1
-default server which will be used if no shard is specified ("hash_host").  If
-you want the default server to be one of the shard servers (e.g. hash_host_a),
-it's easiest to do:
-
-  DB=Sequel.connect('postgres://hash_host_a/hashes', :servers=>servers)
-
-That will still set up a second pool of connections for the default server,
-since it considers the default server and shard servers independent.  Note that
-if you always set the shard on a dataset before using it in queries, it will
-not attempt to connect to the default server.  Sequel may use the default
-server in queries it generates itself, such as to get column names or table
-schemas, so you should always have a default server that works.
-
-To set the shard for a given query, you use the Dataset#server method:
-
-  DB[:hashes].server(:a).where(:hash=>/31337/)
-  
-That will return all matching rows on the hash_host_a shard that have a hash
-column that contains 31337.
-
-Rainbow tables are generally used to find specific hashes, so to save some
-work, you might want to add a method to the dataset that automatically sets
-the shard to use.  This is fairly easy using a Sequel::Model:
-
-  class Rainbow < Sequel::Model(:hashes)
-    dataset_module do
-      def plaintext_for_hash(hash)
-        raise(ArgumentError, 'Invalid SHA-1 Hash') unless /\A[0-9a-f]{40}\z/.match(hash)
-        server(hash[0...1].to_sym).where(:hash=>hash).get(:plaintext)
-      end
-    end
-  end
-  
-  Rainbow.plaintext_for_hash("e580726d31f6e1ad216ffd87279e536d1f74e606")
-
-The connection pool can be further controlled to change how it handles attempts
-to access shards that haven't been configured.  The default is
-to assume the :default shard.  However, you can specify a
-different shard using the :servers_hash option when connecting
-to the database:
-
-  DB = Sequel.connect('postgres://...', :servers_hash=>Hash.new(:some_shard))
-
-You can also use this feature to raise an exception if an
-unconfigured shard is used:
-
-  DB = Sequel.connect('postgres://...', :servers_hash=>Hash.new{raise 'foo'})
-
-If you specify a :servers_hash option to raise an exception for non configured
-shards you should also explicitly specify a :read_only entry in your :servers option
-for the case where a shard is not specified. In most cases it is sufficient
-to make the :read_only entry the same as the :default shard:
-
-  servers = {:read_only => {}}
-  (('0'..'9').to_a + ('a'..'f').to_a).each do |hex|
-    servers[hex.to_sym] = {:host=>"hash_host_#{hex}"}
-  end
-  DB=Sequel.connect('postgres://hash_host/hashes', :servers=>servers, 
-    :servers_hash=>Hash.new{raise Exception.new("Invalid Server")}) 
-
-=== Sharding Plugin
-
-Sequel comes with a sharding plugin that makes it easy to use sharding with model objects.
-It makes sure that objects retrieved from a specific shard are always saved back to that
-shard, allows you to create objects on specific shards, and even makes sure associations
-work well with shards.  You just need to remember to set to model to use the plugin:
-
-  class Rainbow < Sequel::Model(:hashes)
-    plugin :sharding
-  end
-
-  Rainbow.server(:a).first(:id=>1).update(:plaintext=>'VGM')
-
-If all of your models are sharded, you can set all models to use the plugin via:
-
-  Sequel::Model.plugin :sharding
-
-=== server_block Extension
-
-By default, you must specify the server/shard you want to use for every dataset/action,
-or Sequel will use the default shard.  If you have a group of queries that should use the
-same shard, it can get a bit redundent to specify the same shard for all of them.
-
-The server_block extension adds a Database#with_server method that scopes all database
-access inside the block to the given shard by default:
-
-  DB.extension :server_block
-  DB.with_server(:a) do
-    # this SELECT query uses the "a" shard
-    if r = Rainbow.first(:hash=>/31337/)
-      r.count += 1
-      # this UPDATE query also uses the "a" shard
-      r.save
-    end
-  end
-
-The server_block extension doesn't currently integrate with the sharding plugin, as it
-ties into the Dataset#server method.  This shouldn't present a problem in practice as
-long as you just access the models inside the with_server block, since they will use
-the shard set by with_server by default.  However, you will probably have issues if
-you retrieve the models inside the block and save them outside of the block.  If you
-need to do that, call the server method explicitly on the dataset used to retrieve the
-model objects.
-
-=== arbitrary_servers Extension
-
-By default, Sequel's sharding support is designed to work with predefined shards.  It ships
-with Database#add_servers and Database#remove_servers methods to modify these predefined
-shards on the fly, but it is a bit cumbersome to work with truly arbitrary servers
-(requiring you to call add_servers before use, then remove_servers after use).
-
-The arbitrary_servers extension allows you to pass a server/shard options hash as the
-server to use, and those options will be merged directly into the database's default options:
-
-  DB.extension :arbitrary_servers
-  DB[:rainbows].server(:host=>'hash_host_a').all
-  # or
-  DB[:rainbows].server(:host=>'hash_host_b', :database=>'backup').all
-
-arbitrary_servers is designed to work well in conjunction with the server_block extension:
-
-  DB.with_server(:host=>'hash_host_b', :database=>'backup') do
-    DB.synchronize do
-      # All queries here default to the backup database on hash_host_b
-    end
-  end
-
-If you are using arbitrary_servers with server_block, you may want to
-define the following method (or something similar) so that you don't
-need to call synchronize separately:
-
-  def DB.with_server(*)
-    super{synchronize{yield}}
-  end
-
-The reason for the synchronize method is that it checks out a connection
-and makes the same connection available for the duration of the block.
-If you don't do that, Sequel will probably disconnect from the database
-and reconnect to the database on each request, since connections to
-arbitrary servers are not cached.
-
-Note that this extension only works with the sharded threaded connection
-pool.  If you are using the sharded single connection pool, you need
-to switch to the sharded threaded connection pool before using this
-extension.  If you are passing the :single_threaded option to
-the Database, just remove that option.  If you are setting:
-
-  Sequel.single_threaded = true 
-
-just remove or comment out that code.