ocean-rails

== The Ocean gem

This repository contains the Ocean ruby gem, containing common framework functionality for the Ruby on Rails part of the architecture.

Ocean requires Ruby 2.2 and Ruby on Rails 4.2.0 or later.

{}[http://badge.fury.io/rb/ocean-rails]

=== What does ocean-rails provide?

• base classes for Ocean controllers and models (both SQL and DynamoDB).
• the Api class, which encapsulates all logic for calling other API services. This includes authentication, authorisation, support for BAN and PURGE, making HTTP requests with retries and backoff, sequentially and in parallel, helpers for running AsyncJobs, sending mail, and much more. Many of these are very useful even outside of the Ocean context.
• the RemoteResource class, which allows you to use a remote Ocean resource as if it were local, with full abstraction of hyperlinks and attributes.
• classes which implement Ocean's aggressive caching for controllers and models, and which provide abstractions for collections, matching, searches, grouping, and paging.
• controller renderers for collections and errors of various kinds.
• the AliveController, which is inherited by all Ocean services. Its only action, +index+, is called by Varnish to determine that the service is operational. Fail-over is performed automatically as a result.
• the ErrorController, which intercepts all errors and converts them to the standard Ocean JSON format in the response body.
• templates and generators to set up new Ocean applications and Ocean resources.

Thus, the +ocean-rails+ gem provides all the abstractions you need for creating very terse and powerful controller and model code. It's a good idea to browse the documentation.

=== Documentation

• Ocean gem on Rubygems: https://rubygems.org/gems/ocean-rails
• Ocean gem API: http://rdoc.info/github/OceanDev/ocean-rails/frames
• Ocean framework: http://wiki.oceanframework.net
• Ocean mailing list: http://groups.google.com/group/oceanframework
• Ocean blog: http://blog.oceanframework.net

=== Creating an Ocean Rails app

Cf. the tutorial at http://wiki.oceanframework.net/index.php/Tutorial for information on about how to set up an Ocean Rails app and create Ocean Resources for it.

=== Running the specs

There are no runtime dependencies. Simply run:

bundle exec rspec

All tests should pass.

=== Rails console

The Rails console is available from the built-in dummy application:

cd spec/dummy rails console

You're now in a sandbox environment (thanks to +webmock+): HTTP accesses are disallowed; each HTTP access you make will be intercepted with a message describing exactly how to mock it away.

To enable HTTP traffic:

WebMock.allow_net_connect!

Please refer to the +webmock+ gem documentation for full information. It's possible to prevent traffic only to specific hosts (e.g. +localhost+).

When you leave the console, you must navigate back to the Rails directory (cd ../..) in order to be able to run RSpec again.