plek 1.10.0 → 1.11.0

data/LICENCE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Crown Copyright
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,27 +1,29 @@
-Plek
-====
+# Plek
 
-"Plek" is Afrikaans. It means "Location." Plek is used to generate the correct hostnames for internal GOV.UK services, eg:
+"Plek" is Afrikaans. It means "Location". Plek is used to generate the correct
+base URLs for internal GOV.UK services, eg:
 
 ```ruby
 Plek.find('frontend')
 ```
 
-returns `https://frontend.production.alphagov.co.uk`. This means we can use this in our code and let our environment configuration figure out the correct hosts for us at runtime.
+returns `http://frontend.dev.gov.uk` on a development machine and
+`https://frontend.production.alphagov.co.uk` on a production machine. This
+means we can use this in our code and let our environment configuration figure
+out the correct hosts for us at runtime.
 
-Hacking Plek URLs
------------------
+## Technical documentation
 
-Plek allows one to alter the URI returned using environment variables, eg:
+See the [API docs](http://www.rubydoc.info/gems/plek) for full details of the API.
 
-```shell
-PLEK_SERVICE_EXAMPLE_CHEESE_THING_URI=http://example.com bundle exec rails s
-```
+### Running the test suite
 
-would set
+`bundle exec rake`
 
-```ruby
-Plek.find('example-cheese-thing')
-```
+## Licence
+
+[MIT License](LICENCE)
+
+## Versioning policy
 
-to `http://example.com`. Underscores in environment variables are converted to dashes in Plek names as demonstrated.
+This is versioned according to [Semantic Versioning 2.0](http://semver.org/)

data/lib/plek.rb

@@ -1,18 +1,60 @@
 require 'plek/version'
 require 'uri'
 
+# Plek resolves service names to a corresponding base URL.
+#
+# It does this by combining the requested service name with information from
+# environment variables.  It will raise a {NoConfigurationError} if a required
+# environment variable isn't set.
+#
+# == Development mode fallback defaults
+#
+# When running development mode (identified by either +RAILS_ENV+ or +RACK_ENV+
+# environment variables being set to "development"), Plek provides some default
+# values when the necessary environment variables aren't set detailed below.
 class Plek
+  # Raised when a required environment variable is not set.
   class NoConfigurationError < StandardError; end
+
+  # The fallback parent domain to use in development mode.
   DEV_DOMAIN = ENV['DEV_DOMAIN'] || 'dev.gov.uk'
+
+  # Domains to return http URLs for.
   HTTP_DOMAINS = [ DEV_DOMAIN ]
 
   attr_accessor :parent_domain
 
+  # Construct a new Plek instance.
+  #
+  # @param domain_to_use [String] Optionally override the parent domain to use.
+  #   If unspecified, this uses the +GOVUK_APP_DOMAIN+ environment variable.
+  #
+  #   In development mode, this falls back to {DEV_DOMAIN} if the environment
+  #   variable is unset.
   def initialize(domain_to_use = nil)
     self.parent_domain = domain_to_use || env_var_or_dev_fallback("GOVUK_APP_DOMAIN", DEV_DOMAIN)
   end
 
-  # Find the URI for a service/application. Return the URI as a string.
+  # Find the base URL for a service/application. This constructs the URL from
+  # the given hostname and the {#parent_domain}. If the {#parent_domain}
+  # matches the {DEV_DOMAIN}, the returned URL will be a http URL, otherwise it
+  # will be https.
+  #
+  # If PLEK_HOSTNAME_PREFIX is present in the environment, it will be prepended
+  # to the hostname.
+  #
+  # The URL for a given service can be overridden by setting a corresponding
+  # environment variable.  eg if +PLEK_SERVICE_EXAMPLE_CHEESE_THING_URI+ was
+  # set, +Plek.new.find('example-cheese-thing')+ would return the value of that
+  # variable.
+  #
+  # @param service [String] the name of the service to lookup.  This should be
+  #   the hostname of the service.
+  # @param options [Hash]
+  # @option options [Boolean] :force_http If true, force the returned URL to be http.
+  # @option options [Boolean] :scheme_relative If true, return a URL without a
+  #   scheme (eg `//foo.example.com`)
+  # @return [String] The base URL for the service.
   def find(service, options = {})
     name = name_for(service)
     if service_uri = defined_service_uri_for(name)
@@ -21,6 +63,10 @@ class Plek
 
     host = "#{name}.#{parent_domain}"
 
+    if host_prefix = ENV['PLEK_HOSTNAME_PREFIX']
+      host = "#{host_prefix}#{host}"
+    end
+
     if options[:scheme_relative]
       "//#{host}"
     elsif options[:force_http] or HTTP_DOMAINS.include?(parent_domain)
@@ -30,27 +76,44 @@ class Plek
     end
   end
 
-  # Find the URI for a service/application. Return a URI object.
+  # Find the base URL for a service/application, and parse as a URI object.
+  # This wraps #find and returns the parsed result.
+  #
+  # @param args see {#find}
+  # @return [URI::HTTPS,URI::HTTP,URI::Generic] The base URL for the service
   def find_uri(*args)
     URI(find(*args))
   end
 
+  # Find the base URL for assets.
+  #
+  # @return [String] The assets base URL.
   def asset_root
     env_var_or_dev_fallback("GOVUK_ASSET_ROOT") { find("static") }
   end
 
+  # Find the base URL for the public website frontend.
+  #
+  # @return [String] The website base URL.
   def website_root
     env_var_or_dev_fallback("GOVUK_WEBSITE_ROOT") { find("www") }
   end
 
+  # Find the base URL for assets.
+  #
+  # @return [URI::HTTPS,URI::HTTP,URI::Generic] The assets base URL.
   def asset_uri
     URI(asset_root)
   end
 
+  # Find the base URL for the public website frontend.
+  #
+  # @return [URI::HTTPS,URI::HTTP,URI::Generic] The website base URL.
   def website_uri
     URI(website_root)
   end
 
+  # @api private
   def name_for(service)
     name = service.to_s.dup
     name.downcase!
@@ -66,10 +129,14 @@ class Plek
     #     Plek.new.find('foo')
     alias_method :current, :new
 
+    # Convenience wrapper.  The same as calling +Plek.new.find+.
+    # @see #find
     def find(*args)
       new.find(*args)
     end
 
+    # Convenience wrapper.  The same as calling +Plek.new.find_uri+.
+    # @see #find_uri
     def find_uri(*args)
       new.find_uri(*args)
     end

data/lib/plek/version.rb

@@ -1,3 +1,3 @@
 class Plek
-  VERSION = '1.10.0'
+  VERSION = '1.11.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: plek
 version: !ruby/object:Gem::Version
-  version: 1.10.0
+  version: 1.11.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-06 00:00:00.000000000 Z
+date: 2015-07-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &16095960 !ruby/object:Gem::Requirement
+  requirement: &15585020 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *16095960
+  version_requirements: *15585020
 - !ruby/object:Gem::Dependency
   name: gem_publisher
-  requirement: &16095460 !ruby/object:Gem::Requirement
+  requirement: &15584460 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,7 +32,7 @@ dependencies:
         version: 1.1.1
   type: :development
   prerelease: false
-  version_requirements: *16095460
+  version_requirements: *15584460
 description: Find the right hostname for each service in an environment-dependent
   manner
 email:
@@ -43,9 +43,11 @@ extra_rdoc_files: []
 files:
 - lib/plek/version.rb
 - lib/plek.rb
+- LICENCE
 - README.md
 homepage: 
-licenses: []
+licenses:
+- MIT
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -58,7 +60,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 3983394480355850721
+      hash: -276749319035868702
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -67,7 +69,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 3983394480355850721
+      hash: -276749319035868702
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.11