wcc-contentful 1.0.8 → 1.1.0

data/lib/wcc/contentful.rb

@@ -34,7 +34,10 @@ module WCC::Contentful
     # Gets the current configuration, after calling WCC::Contentful.configure
     attr_reader :configuration
 
-    attr_reader :types
+    def types
+      ActiveSupport::Deprecation.warn('Use WCC::Contentful::Model.schema instead')
+      WCC::Contentful::Model.schema
+    end
 
     # Gets all queryable locales.
     # Reserved for future use.
@@ -91,7 +94,7 @@ module WCC::Contentful
       end
     end
 
-    @content_types =
+    content_types =
       begin
         if File.exist?(configuration.schema_file)
           JSON.parse(File.read(configuration.schema_file))['contentTypes']
@@ -101,32 +104,35 @@ module WCC::Contentful
         nil
       end
 
-    if !@content_types && %i[if_possible never].include?(configuration.update_schema_file)
+    if !content_types && %i[if_possible never].include?(configuration.update_schema_file)
       # Final fallback - try to grab content types from CDN.  We can't update the file
       # because the CDN doesn't have all the field validation info, but we can at least
       # build the WCC::Contentful::Model instances.
       client = Services.instance.management_client ||
         Services.instance.client
       begin
-        @content_types = client.content_types(limit: 1000).items if client
+        content_types = client.content_types(limit: 1000).items if client
       rescue WCC::Contentful::SimpleClient::ApiError => e
         # indicates bad credentials
         WCC::Contentful.logger.warn("Unable to load content types from API - #{e.message}")
       end
     end
 
-    unless @content_types
+    unless content_types
       raise InitializationError, 'Unable to load content types from schema file or API!' \
         ' Check your access token and space ID.'
     end
 
-    indexer = ContentTypeIndexer.from_json_schema(@content_types)
-    @types = indexer.types
+    # Set the schema on the default WCC::Contentful::Model
+    WCC::Contentful::Model.configure(
+      configuration,
+      schema: WCC::Contentful::ContentTypeIndexer.from_json_schema(content_types).types,
+      services: WCC::Contentful::Services.instance
+    )
 
     # Drop an initial sync
     WCC::Contentful::SyncEngine::Job.perform_later if defined?(WCC::Contentful::SyncEngine::Job)
 
-    WCC::Contentful::ModelBuilder.new(@types).build_models
     @configuration = @configuration.freeze
     @initialized = true
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wcc-contentful
 version: !ruby/object:Gem::Version
-  version: 1.0.8
+  version: 1.1.0
 platform: ruby
 authors:
 - Watermark Dev
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-01-14 00:00:00.000000000 Z
+date: 2022-02-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: byebug
@@ -455,6 +455,7 @@ files:
 - lib/wcc/contentful/middleware/store.rb
 - lib/wcc/contentful/middleware/store/caching_middleware.rb
 - lib/wcc/contentful/model.rb
+- lib/wcc/contentful/model_api.rb
 - lib/wcc/contentful/model_builder.rb
 - lib/wcc/contentful/model_methods.rb
 - lib/wcc/contentful/model_singleton_methods.rb
@@ -495,7 +496,7 @@ homepage: https://github.com/watermarkchurch/wcc-contentful/wcc-contentful
 licenses:
 - MIT
 metadata:
-  documentation_uri: https://watermarkchurch.github.io/wcc-contentful/1.0/wcc-contentful
+  documentation_uri: https://watermarkchurch.github.io/wcc-contentful/1.1/wcc-contentful
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -525,17 +526,18 @@ summary: '[![Gem Version](https://badge.fury.io/rb/wcc-contentful.svg)](https://
   2. [Installation](#installation) 3. [Configuration](#configure) 4. [Usage](#usage)
   1. [Model API](#wcccontentfulmodel-api) 2. [Store API](#store-api) 3. [Direct CDN
   client](#direct-cdn-api-simpleclient) 4. [Accessing the APIs](#accessing-the-apis-within-application-code)
-  5. [Architecture](#architecture) 6. [Test Helpers](#test-helpers) 7. [Advanced Configuration
-  Example](#advanced-configuration-example) 8. [Development](#development) 9. [Contributing](#contributing)
-  10. [License](#license)   ## Why did you rewrite the Contentful ruby stack?  We
-  started working with Contentful almost 3 years ago.  Since that time, Contentful''s
-  ruby stack has improved, but there are still a number of pain points that we feel
-  we have addressed better with our gem.  These are:  * [Low-level caching](#low-level-caching)
-  * [Better integration with Rails & Rails models](#better-rails-integration) * [Automatic
-  pagination and Automatic link resolution](#automatic-pagination-and-link-resolution)
-  * [Automatic webhook management](#automatic-webhook-management)  Our gem no longer
-  depends on any of the Contentful gems and interacts directly with the [Contentful
-  CDA](https://www.contentful.com/developers/docs/references/content-delivery-api/)
+  5. [Architecture](#architecture) 1. [Client Layer](#client-layer) 2. [Store Layer](#store-layer)
+  3. [Model Layer](#model-layer) 6. [Test Helpers](#test-helpers) 7. [Advanced Configuration
+  Example](#advanced-configuration-example) 8. [Connecting to Multiple Spaces](#connecting-to-multiple-spaces-or-environments)
+  9. [Development](#development) 10. [Contributing](#contributing) 11. [License](#license)   ##
+  Why did you rewrite the Contentful ruby stack?  We started working with Contentful
+  almost 3 years ago.  Since that time, Contentful''s ruby stack has improved, but
+  there are still a number of pain points that we feel we have addressed better with
+  our gem.  These are:  * [Low-level caching](#low-level-caching) * [Better integration
+  with Rails & Rails models](#better-rails-integration) * [Automatic pagination and
+  Automatic link resolution](#automatic-pagination-and-link-resolution) * [Automatic
+  webhook management](#automatic-webhook-management)  Our gem no longer depends on
+  any of the Contentful gems and interacts directly with the [Contentful CDA](https://www.contentful.com/developers/docs/references/content-delivery-api/)
   and [Content Management API](https://www.contentful.com/developers/docs/references/content-management-api/)
   over HTTPS.  ### Low-level caching  The wcc-contentful gem enables caching at two
   levels: the HTTP response using [Faraday HTTP cache middleware](https://github.com/sourcelevel/faraday-http-cache),
@@ -552,7 +554,7 @@ summary: '[![Gem Version](https://badge.fury.io/rb/wcc-contentful.svg)](https://
   for one implementation).  Using Faraday makes it easy to add Middleware.  As an
   example, our flagship Rails app that powers watermark.org uses the following configuration
   in Production, which provides us with instrumentation through statsd, logging, and
-  caching: ```rb config.connection = Faraday.new do |builder| builder.use :http_cache,
+  caching: ```ruby config.connection = Faraday.new do |builder| builder.use :http_cache,
   shared_cache: false, store: ActiveSupport::Cache::MemoryStore.new(size: 512.megabytes),
   logger: Rails.logger, serializer: Marshal, instrumenter: ActiveSupport::Notifications  builder.use
   :gzip builder.response :logger, Rails.logger, headers: false, bodies: false if Rails.env.development?
@@ -584,7 +586,7 @@ summary: '[![Gem Version](https://badge.fury.io/rb/wcc-contentful.svg)](https://
   content model registry allows easy definition of custom models in your `app/models`
   directory to override fields.  This plays nice with other gems like algoliasearch-rails,
   which allows you to declaratively manage your Algolia indexes.  Another example
-  from our flagship watermark.org:  ```rb class Page < WCC::Contentful::Model::Page
+  from our flagship watermark.org:  ```ruby class Page < WCC::Contentful::Model::Page
   include AlgoliaSearch  algoliasearch(index_name: ''pages'') do attribute(:title,
   :slug) ... end ```  ### Automatic Pagination and Link Resolution  Using the `contentful_model`
   gem, calling `Page.all.load` does not give you all Page entries if there are more
@@ -678,12 +680,55 @@ summary: '[![Gem Version](https://badge.fury.io/rb/wcc-contentful.svg)](https://
   gives access to the other configured services. You can also include the {WCC::Contentful::ServiceAccessors}
   concern to define these services as attributes in a class.  ```ruby class MyJob
   < ApplicationJob include WCC::Contentful::ServiceAccessors  def perform Page.find(...)  store.find(...)  client.entries(...)
-  end end ```  ## Architecture  ![wcc-contentful diagram](./doc-static/wcc-contentful.png)  ##
-  Test Helpers  To use the test helpers, include the following in your rails_helper.rb:  ```ruby
-  require ''wcc/contentful/rspec'' ```  This adds the following helpers to all your
-  specs:  ```ruby ## # Builds a in-memory instance of the Contentful model for the
-  given content_type. # All attributes that are known to be required fields on the
-  content type # will return a default value based on the field type. instance = contentful_create(''my-content-type'',
+  end end ```  ## Architecture  ![wcc-contentful diagram](./doc-static/wcc-contentful.png)  From
+  the bottom up:  ### Client Layer  The {WCC::Contentful::SimpleClient} provides methods
+  to access the [Contentful  Content Delivery API](https://www.contentful.com/developers/docs/references/content-delivery-api/)
+  through your favorite HTTP client gem.  The SimpleClient expects an Adapter that
+  conforms to the Faraday interface.  Creating a SimpleClient to connect using different
+  credentials, or to connect without setting up all the rest of WCC::Contentful, is
+  easy:  ```ruby WCC::Contentful::SimpleClient::Cdn.new( # required access_token:
+  ''xxxx'', space: ''1234'', # optional environment: ''staging'', # omit to use master
+  default_locale: ''*'', rate_limit_wait_timeout: 10, instrumentation: ActiveSupport::Notifications,
+  connection: Faraday.new { |builder| ... }, ) ```  You can also create a {WCC::Contentful::SimpleClient::Preview}
+  to talk to the Preview API, or a {WCC::Contentful::SimpleClient::Management} to
+  talk to the Management API.  ### Store Layer  The Store Layer represents the data
+  store where Contentful entries are kept for querying.  By default, `WCC::Contentful.init!`
+  creates a {WCC::Contentful::Store::CDNAdapter} which uses a {WCC::Contentful::SimpleClient::Cdn}
+  instance to query entries from the [Contentful Content Delivery API](https://www.contentful.com/developers/docs/references/content-delivery-api/).  You
+  can also query entries from another source like Postgres or an in-memory hash if
+  your data is small enough.  You can also implement your own store if you want!  The
+  gem contains a suite of RSpec shared examples that give you a baseline for implementing
+  your own store. In your RSpec suite: ```ruby # frozen_string_literal: true  require
+  ''my_store'' require ''wcc/contentful/store/rspec_examples''  RSpec.describe MyStore
+  do it_behaves_like ''contentful store'', { # Set which store features your store
+  implements.   nested_queries: true,  # Does your store implement JOINs? include_param:
+  true    # Does your store resolve links when given the :include option? } ```  The
+  store is kept up-to-date by the {WCC::Contentful::SyncEngine}.  The `SyncEngine#next`
+  methodcalls the `#index` method on the configured store in order to update it with
+  the latest data via the [Contentful Sync API](https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/synchronization).  For
+  example, the {WCC::Contentful::Store::MemoryStore} uses this to update the hash
+  with the newest version of an entry, or delete an entry out of the hash.  #### Store
+  Middleware  The store layer is made up of a base store (which implements {WCC::Contentful::Store::Interface}),
+  and optional middleware.  The middleware allows custom transformation of received
+  entries via the `#select` and `#transform` methods.  To create your own middleware
+  simply include {WCC::Contentful::Middleware::Store} and implement those methods,
+  then call `use` when configuring the store:  ```ruby config.store :direct do use
+  MyMiddleware, param1: ''xxx'' end ```  The most useful middleware is the {WCC::Contentful::Middleware::Store::CachingMiddleware},
+  which enables `:lazy_sync` mode (see {WCC::Contentful::Configuration#store})  ###
+  Model Layer  This is the global top layer where your Rails app looks up content
+  similarly to ActiveModel.  The models are namespaced under the root class {WCC::Contentful::Model}.
+  Each model''s implementation of `.find`, `.find_by`, and `.find_all` simply call
+  into the configured Store.  The main benefit of the Model layer is lazy link resolution.  When
+  a model''s property is accessed, if that property is a link that has not been resolved
+  yet (for example using the `include: n` parameter on `.find_by`), the model will
+  automatically call `#find` on the store to resolve that linked entry.  Note that
+  this can easily result in lots of CDN calls to Contentful!  To optimize this you
+  should use the `include` parameter and/or use a different store.  ## Test Helpers  To
+  use the test helpers, include the following in your rails_helper.rb:  ```ruby require
+  ''wcc/contentful/rspec'' ```  This adds the following helpers to all your specs:  ```ruby
+  ## # Builds a in-memory instance of the Contentful model for the given content_type.
+  # All attributes that are known to be required fields on the content type # will
+  return a default value based on the field type. instance = contentful_create(''my-content-type'',
   my_field: ''some-value'') # => #<WCC::Contentful::Model::MyContentType:0x0000000005c71a78
   @created_at=2018-04-16 18:41:17 UTC...>  instance.my_field # => "some-value"  instance.other_required_field
   # => "default-value"  instance.other_optional_field # => nil  instance.not_a_field
@@ -720,16 +765,46 @@ summary: '[![Gem Version](https://badge.fury.io/rb/wcc-contentful.svg)](https://
   \ -s $CONTENTFUL_SPACE_ID -a $CONTENTFUL_MANAGEMENT_TOKEN \ -y -p "$migrations_to_be_run"  echo
   "Updating schema file..." rake wcc_contentful:download_schema ```  All configuration
   options can be found [in the rubydoc](https://www.rubydoc.info/gems/wcc-contentful/WCC/Contentful/Configuration)
-  under {WCC::Contentful::Configuration}   ## Development  After checking out the
-  repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec` to
-  run the tests. You can also run `bin/console` for an interactive prompt that will
-  allow you to experiment.  ## Contributing  Bug reports and pull requests are welcome
-  on GitHub at https://github.com/watermarkchurch/wcc-contentful.  The developers
-  at Watermark Community Church have pledged to govern their interactions with each
-  other, with their clients, and with the larger wcc-contentful user community in
-  accordance with the "instruments of good works" from chapter 4 of The Rule of St.
-  Benedict (hereafter: "The Rule"). This code of ethics has proven its mettle in thousands
-  of diverse communities for over 1,500 years, and has served as a baseline for many
-  civil law codes since the time of Charlemagne.  [See the full Code of Ethics](https://github.com/watermarkchurch/wcc-contentful/blob/master/CODE_OF_ETHICS.md)  ##
+  under {WCC::Contentful::Configuration}  ## Connecting to multiple spaces or environments  When
+  initializing the WCC::Contentful gem using `WCC::Contentful.init!`, the gem will
+  by default connect to the single Contentful space that you specify in the `WCC::Contentful.configure`
+  step.  However the gem is also capable of connecting to multiple spaces within the
+  same ruby process!  You just have to create and initialize a namespace.  The {WCC::Contentful::ModelAPI}
+  concern makes this straightforward.  Start by creating your Namespace and including
+  the concern: ```ruby # app/models/my_second_space.rb class MySecondSpace include
+  WCC::Contentful::ModelAPI end  # app/models/other_page.rb class OtherPage < MySecondSpace::Page
+  end ```  Then configure it in an initializer: ```ruby # config/initializers/my_second_space.rb
+  MySecondSpace.configure do |config| # Make sure to point to a different schema file
+  from your first space! config.schema_file = Rails.root.join(''db/second-contentful-schema.json'')  config.access_token
+  = ENV[''SECOND_CONTENTFUL_ACCESS_TOKEN''] config.preview_token = ENV[''SECOND_CONTENTFUL_PREVIEW_ACCESS_TOKEN'']
+  config.space = ENV[''SECOND_CONTENTFUL_SPACE_ID''] config.environment = ENV[''CONTENTFUL_ENVIRONMENT'']
+  end ```  Finally, use it: ```ruby OtherPage.find(''1234'') # GET https://cdn.contentful.com/spaces/other-space/environments/other-env/entries/1234
+  # => #<OtherPage:0x0000000005c71a78 @created_at=2018-04-16 18:41:17 UTC...>  Page.find(''1234'')
+  # GET https://cdn.contentful.com/spaces/first-space/environments/first-env/entries/1234
+  # => #<Page:0x0000000001271b70 @created_at=2018-04-15 12:02:14 UTC...> ```  The
+  ModelAPI defines a second stack of services that you can access for lower level
+  connections: ```ruby store = MySecondSpace.services.store # => #<WCC::Contentful::Store::CDNAdapter:0x00007f888edac118
+  client = MySecondSpace.services.client # => #<WCC::Contentful::SimpleClient::Cdn:0x00007f88942a8888
+  preview_client = MySecondSpace.services.preview_client # => #<WCC::Contentful::SimpleClient::Preview:0x00007f888ccafa00
+  sync_engine = MySecondSpace.services.sync_engine # => #<WCC::Contentful::SyncEngine:0x00007f88960b6b40
+  ``` Note that the above services are not accessible on {WCC::Contentful::Services.instance}
+  or via the {WCC::Contentful::ServiceAccessors}.  ### Using a sync store with a second
+  space  If you use something other than the CDNAdapter with your second space, you
+  will need to find a way to trigger `MySecondSpace.services.sync_engine.next` to
+  keep it up-to-date.  The {WCC::Contentful::Engine} will only manage the global SyncEngine
+  configured by the global {WCC::Contentful.configure}.  The easiest way to do this
+  is to set up your own Rails route to respond to Contentful webhooks and then configure
+  the second Contentful space to send webhooks to this route. You could also do this
+  by triggering it periodically in a background job using Sidekiq and [sidekiq-scheduler](https://github.com/Moove-it/sidekiq-scheduler).  ##
+  Development  After checking out the repo, run `bin/setup` to install dependencies.
+  Then, run `bundle exec rspec` to run the tests. You can also run `bin/console` for
+  an interactive prompt that will allow you to experiment.  ## Contributing  Bug reports
+  and pull requests are welcome on GitHub at https://github.com/watermarkchurch/wcc-contentful.  The
+  developers at Watermark Community Church have pledged to govern their interactions
+  with each other, with their clients, and with the larger wcc-contentful user community
+  in accordance with the "instruments of good works" from chapter 4 of The Rule of
+  St. Benedict (hereafter: "The Rule"). This code of ethics has proven its mettle
+  in thousands of diverse communities for over 1,500 years, and has served as a baseline
+  for many civil law codes since the time of Charlemagne.  [See the full Code of Ethics](https://github.com/watermarkchurch/wcc-contentful/blob/master/CODE_OF_ETHICS.md)  ##
   License  The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).'
 test_files: []