moonrope 1.4.1 → 2.0.0

data/templates/basic/assets/try.js

@@ -0,0 +1,151 @@
+$(document).ready(function() {
+
+  $form = $('form.tryForm')
+
+  // Get all fields which will be added as headers
+  var headerFields = $('input.headerField', $form)
+
+  // Add stored values to header fields
+  if(typeof(Storage) !== "undefined") {
+    headerFields.each(function() {
+      $field = $(this)
+      $field.val(localStorage.getItem("header__" + $(this).attr('name')))
+    })
+
+  }
+
+
+  //
+  // Form submission
+  //
+  $form.on('submit', function() {
+
+    // Gets values used to make up the URL which should be
+    // requested for this request.
+    var host = $("input[name=host]", $(this)).val()
+    var version = $("input[name=version]", $(this)).val()
+    var controller = $("input[name=controller]", $(this)).val()
+    var action = $("input[name=action]", $(this)).val()
+    var url = host + "/api/" + version + "/" + controller + "/" + action
+    // Get the output box ready for use
+    var outputBox = $('.tryForm__output', $(this))
+    // Create a hash fo all parameters which will be submitted
+    var parameters = {}
+    $('input.paramField').each(function(){
+      $this = $(this)
+      value = $this.val()
+      type = $this.data('type')
+      name = $this.attr('name')
+      if(value.length) {
+        if(type == 'Integer') {
+          parameters[name] = parseInt(value);
+        } else if (type == "Hash" || type == "Array") {
+          parameters[name] = JSON.parse(value);
+        } else {
+          parameters[name] = value;
+        }
+      }
+    });
+
+    // Include/exclude full attributes as needed
+    var fullAttrsCheckbox = $('#full_attrs')
+    if(fullAttrsCheckbox.length) {
+      parameters['_full'] = !!fullAttrsCheckbox.prop('checked')
+    }
+
+    // Include/exclude expansions
+    var expansionCheckboxes = $('.tryForm__expansions')
+    if(expansionCheckboxes.length) {
+      parameters['_expansions'] = []
+      expansionCheckboxes.each(function() {
+        $this = $(this)
+        name = $(this).attr('name')
+        if($(this).prop('checked')) {
+          parameters['_expansions'].push(name)
+        }
+      })
+    }
+
+    // Make the AJAX request
+    $.ajax({
+      url: url,
+      method: 'POST',
+      contentType: 'application/json',
+      data: JSON.stringify(parameters),
+      beforeSend: function(xhr) {
+        // Add any headers which have been added
+        headerFields.each(function() {
+          $field = $(this)
+          name = $field.attr('name')
+          value = $field.val()
+          if(typeof(Storage) !== "undefined") {
+            localStorage.setItem("header__" + name, value)
+          }
+          if(value.length) {
+            xhr.setRequestHeader(name, $field.val())
+          }
+        })
+      },
+      success: function(data) {
+        // Success means that we got a 200 OK which means we can be pretty
+        // sure that we've got a moonrope response.
+        if(data.status == "success") {
+          outputBox.addClass('tryForm__output--success').removeClass('tryForm__output--error')
+        } else {
+          outputBox.addClass('tryForm__output--error').removeClass('tryForm__output--success')
+        }
+        outputBox.text(JSON.stringify(data, null, 4))
+        outputBox.show()
+      },
+      error: function() {
+        // Errors which occurr aren't very well reported at the moment.
+        // They should be.
+        outputBox.show()
+        outputBox.text("Failed to make request.")
+        outputBox.addClass('tryForm__output--error').removeClass('tryForm__output--success')
+      }
+    })
+    return false
+  });
+
+  //
+  // Open the try form
+  //
+  $('p.tryFormActivate a').on('click', function() {
+    $form = $('form.tryForm')
+    $parent = $(this).parents('p')
+    $form.show('fast')
+    $parent.hide()
+    return false
+  });
+
+  //
+  // Close the try form
+  //
+  $('button.tryFormCancel').on('click', function() {
+    $form = $('form.tryForm')
+    $parent = $('p.tryFormActivate')
+    $form.hide()
+    $parent.show()
+    return false
+  });
+
+  // http://stackoverflow.com/questions/8100770/auto-scaling-inputtype-text-to-width-of-value
+  // http://jsfiddle.net/MqM76/217/
+  $.fn.textWidth = function(text, font) {
+      if (!$.fn.textWidth.fakeEl) $.fn.textWidth.fakeEl =      $('<span>').hide().appendTo(document.body);
+      $.fn.textWidth.fakeEl.text(text || this.val() || this.text()).css('font', font || this.css('font'));
+      return $.fn.textWidth.fakeEl.width();
+  };
+
+  // Automatically ensure that the size for the header inputs is
+  // correct
+  function resizeInput() {
+    $this = $(this)
+    $this.css('width', $this.textWidth() + "px")
+    $this.attr('size', $this.val().length)
+  }
+
+  $('form.tryForm .tryForm__header input').on('input', resizeInput).trigger('input')
+
+});

data/templates/basic/authenticator.erb

@@ -0,0 +1,51 @@
+
+<% if authenticator.name == :default %>
+<% set_page_title "Authentication" %>
+<% set_active_nav "authenticator-default" %>
+<h1>Authentication</h1>
+<% else %>
+<% set_page_title "#{humanize(authenticator.name.to_s.capitalize)} Authenticator" %>
+<h1><%= humanize(authenticator.name.to_s.capitalize) %> Authenticator</h1>
+<% end %>
+
+<p class='text'>
+  <%= authenticator.description %>
+</p>
+
+<h2>Authentication Headers</h2>
+<p class='text'>
+  The following headers are used to identify yourself to the API client. These should be
+  sent as standard HTTP headers with any API request.
+</p>
+<table class='table paramTable'>
+  <thead>
+    <tr>
+      <th width="60%">Header</th>
+      <th width="40%">Example</th>
+    </tr>
+  </thead>
+  <% for name, options in authenticator.headers %>
+  <tr>
+    <td>
+      <p>
+        <span class='paramTable__name'><%= name %></span>
+      </p>
+      <% if options[:description] %>
+        <p class='paramTable__description'><%= options[:description] %></p>
+      <% end %>
+    </td>
+    <td><%= options[:eg] || options[:example] %> </td>
+  </tr>
+  <% end %>
+</table>
+
+<h2>Errors</h2>
+<p class='text'>
+  The errors listed below may be raised if any issues occur when verifying your
+  identity with the API.
+</p>
+<% if authenticator.errors.empty? %>
+  <p><em>There are no errors which can be raised.</em></p>
+<% else %>
+  <%= partial "errors_table", :errors => authenticator.errors %>
+<% end %>

data/templates/basic/controller.erb

@@ -0,0 +1,20 @@
+<% set_page_title controller.friendly_name || controller.name %>
+<% set_active_nav "controller-#{controller.name}" %>
+<h1><%= controller.friendly_name || controller.name %></h1>
+<% if controller.description %>
+  <p class='text'><%= controller.description %></p>
+<% end %>
+<h2>Action</h2>
+<p class='text'>
+  The following actions are available. Choose from the list below
+  to view full details of how to access them.
+</p>
+<ul class='standardList'>
+  <% for action in controller.actions.values.select { |a| a.doc != false } %>
+  <li>
+    <a class='link' href='<%= path("controllers/#{action.controller.name}/#{action.name}") %>'><%= action.title || action.name %></a>
+    <p class='apiURL'><span><%= full_prefix %>/</span><b><%= action.controller.name %>/<%= action.name %></b></p>
+    <% if action.description %><p class='meta'><%= action.description %></p><% end %>
+  </li>
+  <% end %>
+</ul>

data/templates/basic/index.erb

@@ -0,0 +1,114 @@
+<% set_page_title "Welcome" %>
+<% set_active_nav "home" %>
+<h1>Welcome to our API documentation</h1>
+<p class='text'>
+  From here you can browse the full documentation for our HTTP
+  API. Our API is split into sections which you can browse using
+  the menu on the right. If you have any questions, you can
+  <a href='#'>contact our team</a> and we'll be happy to help out.
+</p>
+<p class='text'>
+  Before you get started, take a few minutes to review the
+  information below about how to interact with our API. It includes
+  information about how to send requests, what response data is
+  sent in and how to handle errors.
+</p>
+
+<h2>Making requests</h2>
+<p class='text'>
+  Our API works over the HTTP protocol with JSON. It is implemented
+  in an RPC-like manner and everything you can do with the API has
+  its own <em>action</em>.
+</p>
+<p class='text'>
+  All HTTP requests must be made over HTTPS to the URL shown on the
+  action's page in this documentation. All responses you receive from
+  the API will be returned in JSON. Requests should be made using the
+  <code>POST</code> method with any parameters encoded as JSON in the
+  body of the request.
+</p>
+
+<h2>Receiving responses</h2>
+<p class='text'>
+  All responses will be returned to you encoded as JSON. You will always
+  receive a hash as the response which will look like the JSON below:
+</p>
+<pre class='code'>
+{
+  <span class='jsonKey'>"status"</span>:<span class='jsonString'>"success"</span>,
+  <span class='jsonKey'>"time"</span>:<span class='jsonString'>0.123</span>,
+  <span class='jsonKey'>"flags"</span>:{
+    <span class='jsonComment'>... additional information about the request ...</span>
+  },
+  <span class='jsonKey'>"data"</span>:{
+    <span class='jsonComment'>... the data returned from the action ...</span>
+  }
+}
+</pre>
+<p class='text'>
+  The <b>status</b> attribute will give you can indication about whether the
+  request was performed successfully or whether an error occurred. Values which
+  may be returned are shown below:
+</p>
+<ul class='standardList'>
+  <li>
+    <code>success</code> - this means that the request completed successfully
+    and returned the data that was expected.
+  </li>
+  <li>
+    <code>parameter-error</code> - the parameters provided for the action are
+    not valid and should be revised.
+  </li>
+  <li>
+    <code>error</code> - an error occurred that didn't fit into the above categories.
+    This will be accompanied with an error code, a descriptive message and further
+    attributes which may be useful. The actual potential errors for each action are
+    shown in the documentation.
+  </li>
+</ul>
+<p class='text'>
+  The <b>time</b> attribute shows how long the request took to complete on the
+  server side.
+</p>
+<p class='text'>
+  The <b>flags</b> attribute contains a hash of additional attributes
+  which are relevant to your request. For example, if you receive an array of data
+  it may be paginated and this pagination data will be returned in this
+  hash.
+</p>
+<p class='text'>
+  The <b>data</b> attribute contains the result of your request. Depending on the
+  status, this will either contain the data requested or details of any
+  error which has occurred.
+</p>
+<h3>A note about HTTP status code</h3>
+<p class='text'>
+  The API does not generally use HTTP status codes to return information
+  about the outcome of a request. There are two supported statuses with
+  the API:
+</p>
+<ul class='standardList'>
+  <li>
+    <code>200 OK</code> - This is the code you'll usually receive.
+    It indicates that the response was successfully delivered and
+    returned to our service (although does not nessesary mean that
+    the action you were expecting was successful). Further status
+    information will be provided in the <code>status</code> attribute
+    on your response body.
+  </li>
+  <li>
+    <code>301 Moved Permanently</code> or <code>308 Permanent Redirect</code> -
+    This means that the API request should be sent to an alternative
+    URL. This may just mean you need to send your request using <code>https</code>
+    rather than <code>http</code> as the protocol.
+  </li>
+  <li>
+    <code>500 Internal Server Error</code> - This will be returned
+    when an error occurred within the API itself. This was not
+    anticipated by us and should be reported to us.
+  </li>
+  <li>
+    <code>503 Service Unavailable</code> - This will be returned if
+    API is currently unavailable for maintenance or other issue.
+  </li>
+</ul>

data/templates/basic/layout.erb

@@ -0,0 +1,46 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title><%= page_title %> - API Documentation</title>
+    <link href='https://fonts.googleapis.com/css?family=Lato:400,700,900' rel='stylesheet' type='text/css'>
+    <link href='https://fonts.googleapis.com/css?family=Droid+Sans+Mono' rel='stylesheet' type='text/css'>
+    <link rel="stylesheet" href="<%= asset_path('reset.css') %>">
+    <link rel="stylesheet" href="<%= asset_path('style.css') %>">
+  </head>
+  <body>
+    <section class='sidebarBackground'></section>
+    <section class="sidebar">
+      <nav>
+        <ul>
+          <li>
+            <a href='<%= path(:root) %>' class="<%= active_nav == 'home' ? 'active' : '' %>">
+              Home
+            </a>
+          </li>
+          <% if base.authenticators[:default] %>
+          <li>
+            <a href='<%= path('authenticators/default') %>' class="<%= active_nav == 'authenticator-default' ? 'active' : '' %>">
+              Authentication
+            </a>
+          </li>
+          <% end %>
+          <% for controller in base.controllers.select { |c| c.doc != false }.sort_by { |c| c.name.to_s } %>
+          <li>
+            <a href='<%= path("controllers/#{controller.name}") %>' class="<%= active_nav == "controller-#{controller.name}" ? 'active' : '' %>">
+              <%= controller.friendly_name || controller.name %>
+            </a>
+          </li>
+          <% end %>
+        </ul>
+      </nav>
+    </section>
+    <section class='content'>
+      <%= body %>
+    </section>
+    <footer class='footer'>
+      <p>Generated by Moonrope at <%= Time.now.strftime("%H:%M on %A %e %B %Y") %> for <%= git_version[0,6] %></p>
+    </footer>
+    <script src='https://code.jquery.com/jquery-1.12.0.min.js'></script>
+    <script src='<%= asset_path('try.js') %>'></script>
+  </body>
+</html>

data/templates/basic/structure.erb

@@ -0,0 +1,23 @@
+<% set_page_title "#{humanize(structure.name.capitalize)} Structure" %>
+
+<h1><%= humanize(structure.name.capitalize) %> Structure</h1>
+
+<h2>Base Attributes</h2>
+<%= partial 'structure_attributes_list', :structure => structure, :attributes => structure.attributes[:basic].select { |a| a.doc != false } %>
+
+<% full_attrs = structure.attributes[:full].select { |a| a.doc != false } %>
+<% unless full_attrs.empty? %>
+<h2>Extended Attributes</h2>
+<%= partial 'structure_attributes_list', :structure => structure, :attributes => full_attrs %>
+<% end %>
+
+<% if !structure.attributes[:expansion].empty? || !structure.expansions.empty? %>
+<h2>Expansions</h2>
+<p class='text'>
+  Expansions are embedded structures of other objects that are related to the structure
+  that you're viewing. Which expansions are returned by a specific action are shown on that
+  action's documentation however some actions allow you to choose which expansions are
+  returned.
+</p>
+<%= partial 'structure_attributes_list', :structure => structure, :attributes => structure.attributes[:expansion], :expansions => structure.expansions.select { |k,v| v[:doc] != false} %>
+<% end %>

data/test/test_helper.rb

@@ -0,0 +1,81 @@
+require 'test/unit'
+require 'rack/test'
+require 'moonrope'
+
+class Test::Unit::TestCase
+
+  private
+
+  def make_rack_env_hash(path, params = {}, other_env = {})
+    request = Rack::Test::Session.new(nil)
+    request.send :env_for, path, {:params => params, :method => 'POST'}.merge(other_env)
+  end
+
+end
+
+#
+# A fake base object for models
+#
+class ModelBase
+  def initialize(attributes = {})
+    attributes.each do |key, value|
+      instance_variable_set("@#{key}", value)
+    end
+  end
+end
+
+class Animal < ModelBase
+  attr_accessor :id, :name, :color, :user
+end
+
+class User < ModelBase
+  attr_accessor :id, :username, :private_code, :admin
+  def animals
+    @animals ||= []
+  end
+end
+
+class UserWithUnderscore < User
+  class << self
+    def name
+      s = Struct.new(:underscore, :to_s).new
+      s.to_s = 'User'
+      s.underscore = 'user'
+      s
+    end
+  end
+end
+
+#
+# A fake request class for use in some tests
+#
+class FakeRequest
+
+  def initialize(options = {})
+    @options = options
+  end
+
+  def params
+    @params ||= Moonrope::ParamSet.new(@options[:params] || {})
+  end
+
+  def version
+    @options[:version]
+  end
+
+  def identity
+    @options[:identity]
+  end
+
+  def action
+    nil
+  end
+
+end
+
+#
+# Require all tests
+#
+Dir[File.expand_path("../tests/**/*.rb", __FILE__)].each do |filename|
+  require filename
+end

data/test/tests/action_access_test.rb

@@ -0,0 +1,63 @@
+class ActionAccessTest < Test::Unit::TestCase
+
+  def setup
+    @base = Moonrope::Base.new do
+      authenticator :default do
+        rule :default, "AccessDenied" do
+          identity == :admin
+        end
+
+        rule :anonymous, "MustBeAnonymous" do
+          identity.nil?
+        end
+      end
+    end
+    @controller = Moonrope::Controller.new(@base, :users)
+  end
+
+  def test_action_uses_default_access_rule_by_default
+    action = Moonrope::Action.new(@controller, :list)
+    # no authentication has been provided
+    assert_equal false, action.check_access
+    # authentication which is not correct
+    authenticated_request = FakeRequest.new(:identity => :dave)
+    assert_equal false, action.check_access(authenticated_request)
+    # authentication which is correct
+    authenticated_request = FakeRequest.new(:identity => :admin)
+    assert_equal true, action.check_access(authenticated_request)
+  end
+
+  def test_action_can_use_controller_rule
+    controller = Moonrope::Controller.new(@base, :users) do
+      access_rule :anonymous
+    end
+    action = Moonrope::Action.new(controller, :list)
+    # anonymous is ok
+    assert_equal true, action.check_access
+    # with a user is not
+    authenticated_request = FakeRequest.new(:identity => :dave)
+    assert_equal false, action.check_access(authenticated_request)
+  end
+
+  def test_action_can_use_action_rule
+    action = Moonrope::Action.new(@controller, :list) do
+      access_rule :anonymous
+    end
+    # anonymous is ok
+    assert_equal true, action.check_access
+    # with a user is not
+    authenticated_request = FakeRequest.new(:identity => :dave)
+    assert_equal false, action.check_access(authenticated_request)
+  end
+
+  def test_that_invalid_rule_names_raise_errors
+    action = Moonrope::Action.new(@controller, :list) do
+      access_rule :missing
+    end
+    # anonymous is ok
+    assert_raises Moonrope::Errors::MissingAccessRule do
+      action.check_access
+    end
+  end
+
+end