graphiti 2.0.0.beta.2 → 2.0.0.beta.4

data/docs/topics/customizing-sideloads.md

@@ -0,0 +1,156 @@
+---
+title: 'Customizing Sideloads'
+---
+
+# Customizing Sideloads
+> [See the code in our sample app](https://github.com/graphiti-api/employee_directory/commit/e5dbb24b7e5853a9f39aed455a5d318d303df37e)
+
+This cookbook will help you understand sideloading. It would be great to
+live in a world where everything follows default ActiveRecord table
+conventions, but in my experience this is rarely the case. From legacy
+code to alternate datastores, we need to think in Real World terms.
+
+Our [Employee Directory](https://github.com/graphiti-api/employee_directory) sample application
+has a clean schema - let's screw with it. Let's say `Department` has a column called `watcher_emails`, which is an array of strings. We want to sideload `Department > Watchers`. Though the *relationship* is called `watchers`, these will be `Employee` records.
+
+Let's start by adding a spec:
+
+```ruby
+# spec/resources/department/reads_spec.rb
+
+describe 'sideloading' do
+  describe 'watchers' do
+    let!(:employee1) { create(:employee) }
+    let!(:employee2) { create(:employee) }
+    let!(:employee3) { create(:employee) }
+    let!(:department) do
+      create :department,
+        watcher_emails: [employee1.email, employee3.email]
+    end
+
+    before do
+      params[:include] = 'watchers'
+    end
+
+    it 'sideloads employees via watcher_emails' do
+      render
+      sl = d[0].sideload(:watchers)
+      expect(sl.map(&:id)).to eq([employee1.id, employee3.id])
+      expect(sl.map(&:jsonapi_type).uniq).to eq(['employees'])
+    end
+  end
+end
+```
+
+Add the relationship:
+
+```ruby
+# app/resources/department_resource.rb
+has_many :watchers, resource: EmployeeResource
+```
+
+Run the test and you'll get this error:
+
+```error
+Graphiti::Errors::AttributeError:
+  EmployeeResource: Tried to filter on attribute :department_id, but could not find an attribute with that name.
+```
+
+How would we track down this error? Well, we know Resources connect
+together with [Links](/concepts/links). Let's
+take a look at the query parameters that would be used to connect these
+two Resources:
+
+```ruby
+has_many :watchers, resource: EmployeeResource do
+  params do |hash, departments|
+    binding.pry
+  end
+end
+```
+
+> Note - we're using [pry](https://github.com/pry/pry) to debug here.
+
+The value of `hash` here is:
+
+```ruby
+{ filter: { department_id: "1" } }
+```
+
+Which makes sense. If we say `has_many :things`, by default we expect `Thing` to have a `department_id` we can query.
+
+That's not our case, though. Instead, let's customize those parameters
+to fit our use case:
+
+```ruby
+params do |hash, departments|
+  emails = departments.map(&:watcher_emails).flatten
+  hash[:filter] = { email: emails }
+end
+```
+
+Instead of querying by `department_id`, we need to query by `email`. And
+the value we pass in will be an array of email addresses
+
+We'd need to add an `email` filter to `EmployeeResource` to make this
+work. This gets us ***querying*** correctly, but there's another error:
+
+```error
+undefined method `department_id' for #<Employee:0x00007f9652ae6d80>
+```
+
+Here's the thing to keep in mind: let's say our request was
+`/departments?include=watchers`. We queried all the data, and we now have an array of `Department`s and an array of `Employee`s. Now we need
+to specify which employees should be assigned as watchers of which
+department.
+
+Let's write that code manually:
+
+```ruby
+has_many :watchers, resource: EmployeeResource do
+  # ... code ...
+  assign do |departments, employees|
+    departments.each do |d|
+      d.watchers = employees.select do |e|
+        e.email.in?(d.watcher_emails)
+      end
+    end
+  end
+end
+```
+
+We're selecting all relevant `Employee`s for a given `Department` by checking the array of `watcher_emails`.
+
+This code can be tightened up a little with `assign_each` (recommended).
+This way we don't have to iterate departments or worry about the
+assignment ourselves:
+
+```ruby
+has_many :watchers, resource: EmployeeResource do
+  # ... code ...
+
+  assign_each do |department, employees|
+    employees.select { |e| e.email.in?(d.watcher_emails) }
+  end
+end
+```
+
+We're using `#select` to return an array of relevant `Employee`s. If this was a `belongs_to` or `has_one` relationship, we'd probably want to use `#find` to return a single `Employee`.
+
+OK there's *one last error*:
+
+```error
+undefined method `watchers=' for #<Department:0x00007feb625a7468>
+```
+
+This one is simple - the `assign` function will call your Adapter's assignment logic, which by default will be a simple `department.watchers
+= relevant_employees`. That means we need to add a getter/setter for
+this property:
+
+```ruby
+# app/models/department.rb
+attr_accessor :watchers
+```
+
+And we're done! The test should now pass. [Check out the working code
+here](https://github.com/graphiti-api/employee_directory/tree/customize_sideloads_cookbook).

data/docs/topics/debugging.md

@@ -0,0 +1,216 @@
+---
+title: 'Debugging'
+---
+
+## Debugger {#debugger}
+
+Graphiti comes with a debugger that shows the queries executed for a
+given request. Remember that Resources [have a query interface](/concepts/resources#query-interface) independent of a request or response. And Resources connect similar to ActiveRecord's `includes`:
+
+```ruby
+employees = EmployeeResource.all
+PositionResource.all(filter: { employee_id: employees.map(&:id) })
+```
+
+> *Remember, this is all [customizable](/concepts/relationships#customizing-relationships)*.
+
+That means we can log the requests made by individual Resources:
+
+`/api/v1/employees?include=notes,positions.department.teams`
+<p align="center">
+  <img width="100%" src="/assets/img/legacy/legacy-a2cc4363c3.png" />
+</p>
+
+And even copy/paste these queries into a console session to debug:
+
+```bash
+$ bin/rails c
+>> TeamResource.all({:filter=>{:department_id=>"1,2,3"}})
+```
+
+If you're having trouble with a request, see if you can isolate to a
+specific Resource, then test that Resource directly.
+
+Finally: if an error occurs, we'll note the query that caused it:
+
+<p align="center">
+  <img width="100%" src="/assets/img/legacy/legacy-05bbd3e5fd.png" />
+</p>
+
+### JSON Output {#json-output}
+
+It can be helpful to have this debug output come back as part of the
+JSON response. To enable this:
+
+```ruby
+# app/controllers/application_controller.rb
+def allow_graphiti_debug_json?
+  true
+  # or, current_user.admin?
+  # or, Rails.env.development?
+end
+```
+
+And request the debug output:
+
+`/your/url?debug=true`
+
+You should now see the debug output in `meta`:
+
+<p align="center">
+  <img width="100%" src="/assets/img/legacy/legacy-7f6889bc89.png" />
+</p>
+
+<br />
+
+If there's an error, and you've [enabled raw errors](/topics/error-handling#displaying-raw-errors), you'll also see the query that caused the error in the JSON response:
+
+<br />
+
+<p align="center">
+  <img width="100%" src="/assets/img/legacy/legacy-f67cfa89ab.png" />
+</p>
+
+<br />
+
+### Configuration {#configuration}
+
+By default, we'll log to `Rails.logger`, and only enable debugging (logs or JSON) when `Rails.logger.level` is set to `debug`. Here are the
+various ways to configure.
+
+Use `config.debug` to explicitly toggle debugging:
+
+```ruby
+# config/initializers/graphiti.rb
+Graphiti.configure do |c|
+  c.debug = false
+end
+
+# Or use environment variable
+# GRAPHITI_DEBUG=false
+```
+
+Use `config.debug_models` to get additional (but verbose) output:
+
+<p align="center">
+  <img width="100%" src="/assets/img/legacy/legacy-3076df6209.png" />
+</p>
+
+```ruby
+# config/initializers/graphiti.rb
+Graphiti.configure do |c|
+  c.debug_models = true
+end
+
+# Or use environment variable
+# GRAPHITI_DEBUG_MODELS=true
+```
+
+As noted above, `allow_graphiti_debug_json?` must return `true` if you
+want JSON output:
+
+```ruby
+# app/controllers/application_controller.rb
+def allow_graphiti_debug_json?
+  true
+  # or, current_user.admin?
+  # or, Rails.env.development?
+end
+```
+
+Note you need to explicitly pass `?debug=true` in the request.
+
+Assign a different logger:
+
+```ruby
+Graphiti.logger = Logger.new(...)
+
+# Or the built-in STDOUT logger:
+Graphiti.logger = Graphiti.stdout_logger
+```
+
+Manually apply the debugging (when using Rails, this normally happens in
+a `around_action`):
+
+```ruby
+Graphiti::Debugger.debug do
+  EmployeeResource.all
+end
+```
+
+### Rake Tasks {#rake-tasks}
+
+There are some common debugging scenarios that are possible to do
+manually, but their frequency warrants common patterns. For these, we
+have rake tasks.
+
+#### graphiti:request {#graphiti-request}
+
+> `bin/rake graphiti:request[PATH,DEBUG]`
+
+Execute a request using `ActionDispatch::Integration::Session` (which
+underlies request specs).
+
+This can be helpful when you don't have, or don't want to spin up, a web
+server. Imagine you want to debug something on production, so you shell
+into a docker container and edit some files locally. Now you want to
+execute a request and see if your changes worked:
+
+```bash
+$ bin/rake graphiti:request[/employees]
+```
+
+Will execute the request and spit out the JSON response. You may want to
+run with the Debugger enabled:
+
+```bash
+$ bin/rake graphiti:request[/employees,true]
+```
+
+Which add Debugger output as well.
+
+The `PATH` should not contain the domain unless you want to hit a live
+API instead of a test server.
+
+#### graphiti:benchmark {#graphiti-benchmark}
+
+> `bin/rake graphiti:benchmark[PATH,NUM_REQUESTS]`
+
+It can be helpful to run a quick benchmark without hitting a live web
+server, to eliminate the vagaries of latency. To do this:
+
+```bash
+$ bin/rake graphiti:benchmark[/employees,100]
+```
+
+Which will return the average response time.
+
+#### Authorization headers {#Authorization-headers}
+
+If you have an Authorization scheme implemented (for example [authenticate_or_request_with_http_token](https://api.rubyonrails.org/classes/ActionController/HttpAuthentication/Token.html) in rails) you can supply the `Authorization` http header value with the `AUTHORIZATION_HEADER` environment variable:
+
+```bash
+$ export AUTHORIZATION_HEADER="Token --PRIVATE_API_KEY--"
+$ bin/rake graphiti:request[/employees,true]
+```
+
+This also will work for `Basic` ([request_http_basic_authentication](https://api.rubyonrails.org/classes/ActionController/HttpAuthentication/Basic.html$$)) and `Bearer` values
+
+## Tips {#tips}
+
+When debugging an application, try to isolate the individual Resource
+call and debug the Resource directly (instead of running the entire
+request). This helps eliminate variables, and plain ruby code is easier
+to work with. If possible, try to remove Graphiti entirely and focus on
+your Models and Backends.
+
+The most common scenario is debugging a query. We suggest overriding
+`resolve` and using [pry](https://github.com/pry/pry) (or equivalent):
+
+```ruby
+# Introspect the scope without firing a query
+# Call 'super' to fire the query
+def resolve(scope)
+  binding.pry
+end
+```

data/docs/topics/error-handling.md

@@ -0,0 +1,210 @@
+---
+title: 'Error Handling'
+---
+
+## Overview {#overview}
+
+Whenever we have an application error, we want to respond with a
+[JSONAPI-compliant errors payload](http://jsonapi.org/format/#errors).
+This way clients have a predictable response detailing information about
+the error.
+
+```json
+{
+  "errors": [
+    {
+      "code": "internal_server_error",
+      "status": "500",
+      "title": "Internal Server Error",
+      "detail": "We've notified our engineers and hope to address this issue shortly."
+    }
+  ]
+}
+```
+
+We'll also need a way to customize this payload. For instance, if a
+`NotAuthorized` error is raised, the response should have a `403` status
+code. For other errors, we may want to render a helpful error message:
+
+```ruby
+class ApplicationController < ActionController::API
+  register_exception NotAuthorized, status: 403
+  register_exception ShipmentDelayed,
+    detail: ->(e) { "Contact us at 123-456-7899" }
+  # ... code ...
+end
+```
+
+Exception handling lives in Graphiti's Rails integration. Customizing the behavior based on error class happens in the [RescueRegistry](https://github.com/wagenet/rescue_registry) dependency.
+
+### Setup {#setup}
+
+Include the Rails integration in the controllers serving your resources:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include Graphiti::Rails::Controller
+end
+```
+
+That registers handlers for Graphiti's own exceptions and renders anything else as JSON:API. `register_exception` itself is available on every controller without it. See below.
+
+#### Displaying Raw Errors {#displaying-raw-errors}
+
+When raw errors are on, the same payload carries the underlying exception under `meta.__raw_error__`:
+
+```json
+{
+  "errors": [
+    {
+      "code": "internal_server_error",
+      "status": "500",
+      "title": "Internal Server Error",
+      "detail": "We've notified our engineers and hope to address this issue shortly.",
+      "meta": {
+        "__raw_error__": {
+          "message": "EmployeesController::SomeError",
+          "backtrace": [
+            "app/controllers/employees_controller.rb:5:in `index'",
+            "..."
+          ]
+        }
+      }
+    }
+  ]
+}
+```
+
+
+It can be useful to display the raw error as part of the JSON response -
+but you probably don't want to expose your stack trace to customers.
+Let's only show raw errors for the `staging` environment:
+
+```ruby
+class ApplicationController < ActionController::API
+  # ... code ...
+
+  def show_detailed_exceptions?
+    Rails.env.staging?
+  end
+end
+```
+
+Another common pattern is to only show raw errors when the user is
+privileged to see them:
+
+```ruby
+class ApplicationController < ActionController::API
+  # ... code ...
+
+  def show_detailed_exceptions?
+    current_user.admin?
+  end
+end
+
+```
+
+When `#show_detailed_exceptions?` returns `true`, you'll get the raw error class,
+message, and backtrace in the JSON response.
+
+## Usage {#usage}
+
+### Basic {#basic}
+
+Let's register an error with a custom response code:
+
+```ruby
+register_exception Errors::NotAuthorized, status: 403
+```
+
+Now if we `raise Errors::NotAuthorized`, the response code will be `403`.
+
+Additional options:
+
+```ruby
+register_exception Errors::NotAuthorized,
+  status: 403,
+  title: "You cannot perform this action",
+  detail: :exception, # render the raw error message
+  detail: ->(error) { "Invalid Action" } # message via proc
+```
+
+[See full documentation in the RescueRegistry README](https://github.com/wagenet/rescue_registry).
+
+All controllers will inherit any registered exceptions from their parent. They can also add their own. In this example, `FooError` will only throw a custom status code when thrown from `FooController`:
+
+```ruby
+class FooController < ApplicationController
+  register_exception FooError, status: 422
+end
+```
+
+### Advanced {#advanced}
+
+The final option `register_exception` accepts is `handler`. Here you can inject your own error handling class that customize `RescueRegistry::ExceptionHandler`. For example:
+
+```ruby
+class MyCustomHandler < Graphiti::Rails::ExceptionHandler
+  # self.exception accessible within all instance methods
+
+  def status_code
+    # ...customize...
+  end
+
+  def error_code
+    # ...customize...
+  end
+
+  def title
+    # ...customize...
+  end
+
+  def detail
+    # ...customize...
+  end
+
+  def meta
+    # ...customize...
+  end
+end
+
+register_exception FooError, handler: MyCustomHandler
+```
+
+If you would like to use the same custom handler for all errors, override `default_exception_handler`:
+
+```ruby
+# app/controllers/application_controller.rb
+def self.default_exception_handler
+  MyCustomHandler
+end
+```
+
+## Testing {#testing}
+
+This pattern of globally rescuing exceptions makes sense when
+running our live application...but during testing, we may want to
+raise real errors and bypass this rescue logic.
+
+This is why we turn off error-handling during tests by default:
+
+```ruby
+# spec/rails_helper.rb
+RSpec.configure do |config|
+  config.include Graphiti::Rails::TestHelpers
+  # ... code ...
+
+  config.before :each do
+    handle_request_exceptions(false)
+  end
+end
+```
+
+If you want to turn this on for an individual test (so you can test
+error codes, etc):
+
+```ruby
+before do
+  handle_request_exceptions(true)
+end
+```

data/docs/topics/etags.md

@@ -0,0 +1,46 @@
+---
+title: 'ETags'
+---
+
+# ETags
+
+Every resource proxy can compute a weak ETag for its current result set via `proxy.etag`. It's a plain string. Graphiti doesn't wire up `If-None-Match` handling or send `304 Not Modified` responses itself, so using it for HTTP conditional requests is up to your controller (for example, with Rails' own `fresh_when`/`stale?`).
+
+## How it's computed
+
+`etag` is a weak ETag built from the same cache key used for [caching](/topics/caching), but the *versioned* one:
+
+```ruby
+def etag
+  "W/#{ActiveSupport::Digest.hexdigest(cache_key_with_version.to_s)}"
+end
+```
+
+`cache_key_with_version` combines the scope's versioned cache key (which folds in every sideloaded proxy's versioned cache key and the underlying object's own `cache_key_with_version`), the query's cache key, and the resource cache tag if one is configured. Those are the same three ingredients described in the caching doc, except the scope portion here is version-aware rather than the plain identity-only key. In practice this means the ETag changes whenever the resolved records' `updated_at` values change, or whenever the rendering-relevant query params (fields, extra_fields, links, pagination_links, format) change.
+
+Because it's derived purely from `cache_key_with_version`, calling `etag` twice on equivalent proxies (same resource, scope, and query) produces the same weak ETag, and it's always prefixed with `W/`.
+
+## Using it
+
+Since there's no built-in controller integration, you compute and use it explicitly:
+
+```ruby
+def index
+  employees = EmployeeResource.all(params)
+  response.headers["ETag"] = employees.etag
+  render jsonapi: employees
+end
+```
+
+Or combine it with Rails' conditional-GET support if you want automatic `304` handling:
+
+```ruby
+def index
+  employees = EmployeeResource.all(params)
+  fresh_when(etag: employees.etag)
+end
+```
+
+## Relationship to resource-level caching
+
+`etag` doesn't require `cache_resource` or `Graphiti.config.cache_rendering = true`. It's available on any resource proxy regardless of whether that resource participates in rendering caching. It does, however, share its key ingredients with the cache-rendering machinery: the same `cache_key_with_version` that ETags are hashed from is also what `Graphiti::Util::CacheDebug` tracks (as `current_version[:etag]` / `last_version[:etag]`) when the [debugger](/topics/debugging) reports on cache-key changes for a cached resource. So if you're seeing an ETag change unexpectedly, the debugger's cache section (enabled the same way as for [caching](/topics/caching)) will show you which cache-key segment changed.