strelka-cors 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 48fb286bb78b2e0b3b07f2882a1ea18b6f8a341d
+  data.tar.gz: 3f7e5b4603ddd26fdd2b6b08f2276084383c6337
+SHA512:
+  metadata.gz: 25e395f533d5ffd157fcad3bbf70bb5cfa40d7481b25eb2229f46428164e0155a0b1f2a7c5109b8197b9e6b793d8c9fce0d6b50d90b734bebf7e52db9497bb91
+  data.tar.gz: 765eb6ca99a5653c3d630919b6b28c853bc9aa7b50c73cb70738a0e6a1e571ef781de0e5400420b4efa07efab6b28f32f30b7a9efb8a9511cf73cb5022621e70

data/ChangeLog

@@ -0,0 +1,52 @@
+2016-11-03  Michael Granger  <ged@FaerieMUD.org>
+
+	* History.md:
+	Update history.
+	[7f93206d73ef] [tip]
+
+	* certs/ged.pem, strelka-cors.gemspec:
+	Add my gem cert and update the gemspec.
+	[3b0e5784e4c1]
+
+	* .hgignore, .hoerc, History.md, Manifest.txt, README.md, data
+	/strelka-cors/apps/cors-demo, data/strelka-
+	cors/templates/layout.tmpl, data/strelka-cors/templates/top.tmpl,
+	lib/strelka/app/cors.rb, lib/strelka/cors.rb,
+	lib/strelka/httpresponse/cors.rb, spec/strelka/app/cors_spec.rb,
+	spec/strelka/cors_spec.rb, spec/strelka/httpresponse/cors_spec.rb:
+	Finish up initial implementation.
+	[608d8c7cdb47] [github/master]
+
+2016-07-27  Michael Granger  <ged@FaerieMUD.org>
+
+	* .gems, .hgignore, .ruby-gemset, .ruby-version, .rvm.gems, .rvmrc,
+	History.md, History.rdoc, README.md, README.rdoc, Rakefile,
+	lib/strelka/app/cors.rb, lib/strelka/cors.rb,
+	lib/strelka/httprequest/cors.rb, lib/strelka/httpresponse/cors.rb,
+	spec/strelka/app/cors_spec.rb,
+	spec/strelka/httprequest/cors_spec.rb,
+	spec/strelka/httpresponse/cors_spec.rb:
+	Flesh out the API, add request/response convenience method
+	[d9d38f5b5817]
+
+2014-02-27  Michael Granger  <ged@FaerieMUD.org>
+
+	* README.rdoc:
+	Add a project status note to the README
+	[70c8b19774a9]
+
+	* .rvm.gems, .rvmrc, README.rdoc, cors_server_flowchart.png,
+	lib/strelka/app/cors.rb, lib/strelka/cors.rb,
+	lib/strelka/httprequest/cors.rb, spec/helpers.rb,
+	spec/strelka/app/cors_spec.rb, spec/strelka/cors_spec.rb:
+	Started work
+	[516a648b0100]
+
+2013-09-10  Michael Granger  <ged@FaerieMUD.org>
+
+	* .tm_properties, History.rdoc, Manifest.txt, README.rdoc, Rakefile,
+	data/strelka-cors/apps/cors-demo, data/strelka-
+	cors/templates/layout.tmpl, data/strelka-cors/templates/top.tmpl,
+	lib/strelka/cors.rb, spec/strelka/cors_spec.rb:
+	Initial project setup
+	[dbe7b7b1a374]

data/History.md

@@ -0,0 +1,4 @@
+## v0.0.1 [2016-11-03] Michael Granger <ged@FaerieMUD.org>
+
+Initial release.
+

data/Manifest.txt

@@ -0,0 +1,14 @@
+ChangeLog
+History.md
+Manifest.txt
+README.md
+Rakefile
+lib/strelka/app/cors.rb
+lib/strelka/cors.rb
+lib/strelka/httprequest/cors.rb
+lib/strelka/httpresponse/cors.rb
+spec/helpers.rb
+spec/strelka/app/cors_spec.rb
+spec/strelka/cors_spec.rb
+spec/strelka/httprequest/cors_spec.rb
+spec/strelka/httpresponse/cors_spec.rb

data/README.md

@@ -0,0 +1,134 @@
+# strelka-cors
+
+home
+: http://deveiate.org/projects/Strelka-CORS
+
+code
+: http://bitbucket.org/ged/strelka-cors
+
+github
+: https://github.com/ged/strelka-cors
+
+docs
+: http://deveiate.org/code/strelka-cors
+
+
+## Description
+
+This is a Strelka application plugin for describing rules for [Cross-Origin Resource Sharing (CORS)](http://www.w3.org/TR/cors/).
+
+NOTE: It's still a work in progress.
+
+By default, the plugin has paranoid defaults, and doesn't do anything. You'll need to grant access to the resources you want to share.
+
+To grant access, you declare one or more `access_control` blocks which can modify responses to matching access-control requests. All the blocks which match the incoming request's URI are called with the request and response objects in the order in which they're declared: 
+
+	# Allow access to all resources from any origin by default
+	access_control do |req, res|
+		res.allow_origin '*'
+		res.allow_methods 'GET', 'POST'
+		res.allow_credentials
+		res.allow_headers :content_type
+	end
+
+
+These are applied in the order you declare them, with each matching block passed the request if it matches. This happens before the application gets the request, so it can do any further modification it needs to, and so it can block requests from disallowed origins/methods/etc.
+
+There are a number of helper methods added to the request and response objects for applying and declaring access-control rules when this plugin is loaded:
+
+
+### `HTTPResponse#allow_origin <origin>+`
+
+The `origin` parameter specifies a URI that may access the resource by setting the `Access-Control-Allow-Origin` header.
+
+	access_control do |req, res|
+		res.allow_origin 'http://acme.com/', 'http://www.acme.com/
+		res.allow_origin( req.origin )
+		res.allow_origin # same as above
+		res.allow_origin '*'
+	end
+
+
+### `HTTPResponse#expose_headers`
+Specify a whitelist of headers that browsers are allowed to access by setting the `Access-Control-Expose-Headers` header on responses.
+
+	response.expose_headers :content_type, 'x-custom-header'
+
+
+### `HTTPResponse#access_control_max_age`
+
+Specify how long the results of a preflight request can be cached by setting the `Access-Control-Max-Age` header.
+
+
+### `HTTPResponse#allow_credentials`
+
+Specify whether or not a request can be made using credentials by setting the `Access-Control-Allow-Credentials` header on responses.
+
+
+### `HTTPResponse#allow_methods`
+
+Specifies the method or methods allowed when accessing the resource by setting the `Access-Control-Allow-Methods` header on responses.
+
+
+### `HTTPResponse#allow_headers`
+
+Specify the HTTP headers that can be used when making a request.
+
+
+
+
+
+### Allow All Simple Requests
+
+If you just want to allow simple (GET, HEAD, POST) requests to your application
+from any origin, you can do it like so:
+
+    require 'strelka/app'
+    
+    class MyApp < Strelka::App
+        plugin :cors
+        allow_origins '*'
+
+        # The rest of your app
+
+    end
+
+This will add the appropriate header to outgoing responses.
+
+
+## Installation
+
+    gem install strelka-cors
+
+
+## License
+
+Copyright (c) 2015-2016, Michael Granger
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the author/s, nor the names of the project's
+  contributors may be used to endorse or promote products derived from this
+  software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+

data/Rakefile

@@ -0,0 +1,87 @@
+#!/usr/bin/env rake
+
+begin
+	require 'hoe'
+rescue LoadError
+	abort "This Rakefile requires hoe (gem install hoe)"
+end
+
+GEMSPEC = 'strelka-cors.gemspec'
+
+
+Hoe.plugin :mercurial
+Hoe.plugin :signing
+Hoe.plugin :deveiate
+
+
+hoespec = Hoe.spec 'strelka-cors' do |spec|
+	spec.readme_file = 'README.md'
+	spec.history_file = 'History.md'
+	spec.extra_rdoc_files = FileList[ '*.rdoc', '*.md' ]
+	spec.license 'BSD-3-Clause'
+	spec.urls = {
+		home:   'http://deveiate.org/projects/strelka-cors',
+		code:   'http://bitbucket.org/ged/strelka-cors',
+		docs:   'http://deveiate.org/code/strelka-cors',
+		github: 'http://github.com/ged/strelka-cors',
+	}
+
+	spec.developer 'Michael Granger', 'ged@FaerieMUD.org'
+
+	spec.dependency 'strelka', '~> 0.11'
+
+	spec.dependency 'rspec', '~> 3.2', :developer
+	spec.dependency 'simplecov', '~> 0.9', :developer
+	spec.dependency 'timecop', '~> 0.7', :developer
+
+	spec.require_ruby_version( '>=2.2.0' )
+	spec.hg_sign_tags = true if spec.respond_to?( :hg_sign_tags= )
+
+	spec.rdoc_locations << "deveiate:/usr/local/www/public/code/#{remote_rdoc_dir}"
+end
+
+
+ENV['VERSION'] ||= hoespec.spec.version.to_s
+
+# Run the tests before checking in
+task 'hg:precheckin' => [ :check_history, :check_manifest, :gemspec, :spec ]
+
+# Rebuild the ChangeLog immediately before release
+task :prerelease => 'ChangeLog'
+CLOBBER.include( 'ChangeLog' )
+
+desc "Build a coverage report"
+task :coverage do
+	ENV["COVERAGE"] = 'yes'
+	Rake::Task[:spec].invoke
+end
+
+
+# Use the fivefish formatter for docs generated from development checkout
+if File.directory?( '.hg' )
+	require 'rdoc/task'
+
+	Rake::Task[ 'docs' ].clear
+	RDoc::Task.new( 'docs' ) do |rdoc|
+	    rdoc.main = "README.md"
+	    rdoc.rdoc_files.include( "*.rdoc", "*.md", "ChangeLog", "lib/**/*.rb" )
+	    rdoc.generator = :fivefish
+		rdoc.title = 'Strelka-CORS'
+	    rdoc.rdoc_dir = 'doc'
+	end
+end
+
+task :gemspec => [ 'ChangeLog', GEMSPEC ]
+file GEMSPEC => __FILE__ do |task|
+	spec = $hoespec.spec
+	spec.files.delete( '.gemtest' )
+	spec.files.delete( 'LICENSE' )
+	spec.signing_key = nil
+	spec.version = "#{spec.version}.pre#{Time.now.strftime("%Y%m%d%H%M%S")}"
+	File.open( task.name, 'w' ) do |fh|
+		fh.write( spec.to_ruby )
+	end
+end
+
+task :default => :gemspec
+

data/lib/strelka/app/cors.rb

@@ -0,0 +1,111 @@
+# -*- ruby -*-
+# vim: set nosta noet ts=4 sw=4:
+# encoding: utf-8
+
+require 'strelka/app' unless defined?( Strelka::App )
+require 'strelka/httprequest/cors'
+require 'strelka/httpresponse/cors'
+
+
+# Strelka::App plugin module for Cross-Origin Resource Sharing (CORS)
+#
+#     class MyService < Strelka::App
+#         plugins :cors
+#
+#         allow_origins '*'
+#
+#     end # MyService
+#
+# Resources:
+#
+# * http://www.w3.org/TR/cors/
+# * http://enable-cors.org/server.html
+# * http://www.html5rocks.com/en/tutorials/cors/
+#
+module Strelka::App::CORS
+	extend Strelka::Plugin
+
+	run_outside :routing, :restresources, :negotiation
+	run_inside  :errors, :sessions, :auth
+
+
+	# Class methods to add to including applications
+	module ClassMethods
+
+		### Extension hook. Add instance variables to extended classes.
+		def self::extended( mod )
+			mod.instance_variable_set( :@access_controls, [] )
+		end
+
+
+		##
+		# An Array of access control tuples of the form:
+		#   [ <uri_pattern>, <options_hash> ]
+		attr_reader :access_controls
+
+
+		### Get/declare access control rules for requests whose app_path matches the specified
+		### +uri_pattern+, and whose other attributes match the given +options+.
+		def access_control( uri_pattern=nil, **options, &block )
+			options[ :block ] = block if block
+			self.access_controls << [ uri_pattern, options ]
+		end
+		alias_method :cors_access_control, :access_control
+
+	end # module ClassMethods
+
+
+	### Extension callback -- extend the HTTPRequest class with Auth
+	### support when this plugin is loaded.
+	def self::included( object )
+		self.log.debug "Extending Request with CORS mixin"
+		Strelka::HTTPRequest.class_eval { include Strelka::HTTPRequest::CORS }
+		Strelka::HTTPResponse.class_eval { include Strelka::HTTPResponse::CORS }
+		super
+	end
+
+
+	### Extend handled requests with CORS stuff.
+	def handle_request( request )
+		if request.origin
+			self.log.info "Request has an Origin (%p): applying CORS" % [ request.origin ]
+			response = if request.is_preflight?
+					self.log.debug "Preflight request for %s" % [ request.uri ]
+					self.handle_preflight_request( request )
+				else
+					request.response.add_cors_headers
+					super
+				end
+
+			return response
+		else
+			super
+		end
+	end
+
+
+	### Handle a CORS preflight +request+.
+	def handle_preflight_request( request )
+		path = request.app_path
+		response = request.response
+
+		self.class.access_controls.each do |pattern, options|
+			self.log.debug "Applying access controls: %p (%p)" % [ pattern, options ]
+
+			# TODO: Skip requests that don't match options? E.g.,
+			#   next unless options[:allowed_methods].include?( request.verb )
+
+			options[:block].call( request, response ) if
+				options[:block] && ( !pattern || path.match(pattern) )
+		end
+
+		response.add_cors_headers
+		response.status = 204
+
+		return response
+	end
+
+
+end # module Strelka::App::CORS
+
+

data/lib/strelka/cors.rb

@@ -0,0 +1,23 @@
+# -*- ruby -*-
+# vim: set nosta noet ts=4 sw=4:
+# encoding: utf-8
+
+
+require 'strelka' unless defined?( Strelka )
+
+
+module Strelka::CORS
+
+	# The library version
+	VERSION = '0.0.1'
+
+	# Version control revision
+	REVISION = %q$Revision: 608d8c7cdb47 $
+
+
+	require 'strelka/app/cors'
+	require 'strelka/httprequest/cors'
+	require 'strelka/httpresponse/cors'
+
+end # module Strelka::CORS
+

data/lib/strelka/httprequest/cors.rb

@@ -0,0 +1,55 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'strelka/httprequest'
+
+
+# The mixin that adds methods to Strelka::HTTPRequest for
+# Cross-Origin Resource Sharing (CORS).
+module Strelka::HTTPRequest::CORS
+
+
+	### Add some instance variables to the request object.
+	def initialize( * ) # :notnew:
+		super
+		@origin = nil
+	end
+
+
+	######
+	public
+	######
+
+	### Return the URI in the Origin header (if the request has one) as a
+	### URI object. If the request doesn't have an Origin: header, returns
+	### nil.
+	def origin
+		unless @origin
+			origin_uri = self.headers.origin or return nil
+			@origin = URI( origin_uri )
+		end
+
+		return @origin
+	end
+
+
+	### Returns +true+ if the request contains an Origin header whose
+	### URI has a host that's different than its Host: header.
+	def cross_origin?
+		return self.origin && self.headers.host != self.origin.host
+	end
+	alias_method :is_cross_origin?, :cross_origin?
+
+
+	### Returns +true+ if the receiver is a CORS preflight request.
+	def preflight?
+		return self.origin &&
+			self.verb == :OPTIONS &&
+			self.header.access_control_request_method
+	end
+	alias_method :is_preflight?, :preflight?
+
+
+end # module Strelka::HTTPRequest::CORS
+
+