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

data/docs/topics/hopping-relationships.md

@@ -0,0 +1,149 @@
+---
+title: 'Hopping Relationships'
+---
+
+# Hopping Relationships
+> [See the code](https://github.com/graphiti-api/employee_directory/commit/b187127d60ea67ef4c2a326721caeaad21ed7ec9)
+
+Our [sample application](https://github.com/graphiti-api/employee_directory)
+has the setup `Employee > Position > Department`, where one of the positions is the `current_position`. What if we wanted to change this to `Employee > Department`, hiding everything about positions
+under-the-hood?
+
+Let's start by saying an `Employee` has many `Department`s. Here's the
+spec:
+
+```ruby
+describe 'sideloading' do
+  describe 'departments' do
+    let!(:employee) { create(:employee) }
+    let!(:position1) do
+      create :position,
+        historical_index: 2,
+        employee: employee,
+        department: department1
+    end
+    let!(:position2) do
+      create :position,
+        historical_index: 1,
+        employee: employee,
+        department: department2
+    end
+    let!(:department1) { create(:department) }
+    let!(:department2) { create(:department) }
+
+    before do
+      params[:include] = 'departments'
+    end
+
+    it 'finds the departments for all positions' do
+      render
+      sl = d[0].sideload(:departments)
+      expect(sl.map(&:id)).to eq([department1.id, department2.id])
+      expect(sl.map(&:jsonapi_type).uniq).to eq(['departments'])
+    end
+  end
+end
+```
+
+Start by defining the association:
+
+```ruby
+has_many :departments
+```
+
+And you'll get this error:
+
+```error
+Graphiti::Errors::AttributeError:
+  DepartmentResource: Tried to filter on attribute :employee_id, but could not find an attribute with that name.
+```
+
+Which makes sense - if this is a `has_many` association, we'd expect DepartmentResource to filter by `employee_id`. Though in our case we
+don't have that as a foreign key, we can still implement the
+`employee_id` filter:
+
+```ruby
+filter :employee_id, :integer, only: [:eq] do
+  eq do |scope, value|
+    scope.joins(:positions).merge(Position.where(employee_id: value))
+  end
+end
+```
+
+In order to find `Department`s by an `employee_id`, we need to join the `positions` table which has the `employee_id` column.
+
+We now get this error:
+
+```error
+NoMethodError:
+  undefined method `employee_id' for #<Department:0x00007fa6f330f768>
+```
+
+Let's say our URL is `/employees?include=departments`. We've fetched all the `Employee`s and all the `Department`s, now we need to associate each `Department` with its relevant `Employee`. Normally we'd do that by looking at the `employee_id` foreign key on `Department`, but this
+scenario has non-standard logic. Let's tell Graphiti how to select
+relevant `Department`s for a given `Employee`:
+
+```ruby
+has_many :departments do
+  assign_each do |employee, departments|
+    departments.select do |d|
+      employee_ids = d.positions.map(&:employee_id).flatten
+      employee.id.in?(employee_ids)
+    end
+  end
+end
+```
+
+There's one final step - because we're assigning a department to an
+employee, we have to make sure that accessor exists:
+
+```ruby
+# app/models/employee.rb
+attr_accessor :department
+```
+
+
+And that's it! Our test now passes.
+
+There's a little bit of sleight-of-hand above though. Our filter joins
+to the `positions` table, and our assignment iterates over departments and calls `department.positions`. **If we don't eager load, we'll cause
+an N+!**!
+
+There are two solutions to this. The first is to simple change `.joins` to `.eager_load`:
+
+```ruby
+scope.eager_load(:positions).merge(Position.where(employee_id: value))
+```
+
+This ensures that not only are we joining on the `positions` table, we'll eagler load the `positions` *relationship* and avoid the N+1.
+
+If you're a stickler, though, you may have a nitpick. For one, if
+we're hitting `/departments?filter[employee_id]` directly there is no need to eager load `positions` because we're never associating to an `Employee`. We're paying a performance penalty when we don't have to.
+
+OK, let's keep our filter `.joins`. We just have to tell Graphiti to switch it to `.eager_load` when sideloading through `EmployeeResource`:
+
+```ruby
+has_many :departments do
+  # ... code ...
+
+  pre_load do |proxy, employees|
+    proxy.scope.object = proxy.scope.object.eager_load(:positions)
+  end
+end
+```
+
+The `pre_load` hook fires after we've built up the scope, but before we resolve it (before actually firing the query). It yields a `proxy`
+object that we can modify - here we're modifying the scope to eager load
+positions.
+
+It's up to you if you care about this scenario - you may want to start
+with `.eager_load` and only embrace to the extra work of `pre_load` when
+you really need it.
+
+The trick to these customizations is to think in Links. Resources
+connect to each other with URLs - what would the query parameters of the
+URL be? In this case, `filter?[employee_id]=123`. After that, we just
+have to define how to associate relevant objects. Even with complex
+associations hopping several levels, the same logic applies.
+
+See the final code [here](https://github.com/graphiti-api/employee_directory/commit/b187127d60ea67ef4c2a326721caeaad21ed7ec9).

data/docs/topics/json-attributes.md

@@ -0,0 +1,77 @@
+---
+title: 'JSON Attributes'
+---
+
+# JSON Attributes
+
+Graphiti has two built-in types for structured data: `hash` and `array`. Both are useful for serving JSON/JSONB columns (or any nested data) through a Resource, without you writing custom typecasting.
+
+For the full type table, see [Types](/concepts/resources#types). This page covers `hash` and `array` specifically.
+
+## Declaring the attribute {#declaring}
+
+```ruby
+class PostResource < ApplicationResource
+  attribute :metadata, :hash
+  attribute :tags, :array
+end
+```
+
+Like any attribute, this is readable, writable, sortable and filterable by default. If your model reads a `metadata` JSONB column and returns a Ruby `Hash`, `attribute :metadata, :hash` will render it as-is.
+
+## Coercion rules {#coercion}
+
+Each type is a [Dry::Types](https://dry-rb.org/gems/dry-types) triple of `params` (used for filtering/sorting from query strings), `read`, and `write`. Per `lib/graphiti/types.rb`:
+
+* `hash` - `read` and `write` are `Dry::Types["strict.hash"]`. Nothing is coerced beyond requiring a real `Hash`. `params` is a custom type that runs `JSON.parse(input) if input.is_a?(String)` before validating with `Dry::Types["params.hash"]`, so a JSON string arriving in a query param gets parsed automatically.
+* `array` - `read`, `write`, and `params` are all `Dry::Types["strict.array"]`. There is no `.of(...)` constraint, so elements are not individually coerced. Any array (including an array of hashes) passes through as-is.
+
+Both types have `kind: "record"` (`hash`) or `kind: "array"` (`array`) rather than `"scalar"`. One consequence: unlike every other base type (`integer`, `string`, `date`, etc.), `hash` and `array` do **not** get an `array_of_*` doppelgänger generated (`lib/graphiti/types.rb` explicitly excludes `:boolean`, `:hash`, and `:array` when building `array_of_*` variants). If you need an array of hashes, just use `attribute :things, :array` - there's no `array_of_hashes` type.
+
+On coercion failure - reading, writing, or filtering - Graphiti raises `Graphiti::Errors::TypecastFailed` with the attribute name, the offending value, and the underlying error.
+
+## Filtering on a hash attribute {#filtering}
+
+Declaring `attribute :metadata, :hash` makes it filterable with the `eq` operator by default (the `hash` type only supports `eq` out of the box, per the default operator map). A request like:
+
+```
+GET /posts?filter[metadata]={"status":"draft"}
+```
+
+parses the JSON string into a Ruby `Hash` before your filter block runs:
+
+```ruby
+filter :metadata, :hash do
+  eq do |scope, value|
+    # value => [{ "status" => "draft" }]
+    scope
+  end
+end
+```
+
+Note the value is wrapped in an array - Graphiti's filter pipeline supports passing multiple comma-separated JSON objects (`filter[metadata]={"a":1},{"b":2}`), so `eq` always receives an array of hashes unless you opt out.
+
+Pass `single: true` to receive the hash directly instead of an array-wrapped one, and to skip the comma-splitting behavior entirely (useful once your hash values might legitimately contain commas):
+
+```ruby
+filter :metadata, :hash, single: true do
+  eq do |scope, value|
+    # value => { "status" => "draft" }
+    scope
+  end
+end
+```
+
+A Ruby `Hash` (rather than a JSON string) passed directly as a filter param works the same way. It's validated rather than parsed.
+
+Array attributes filter similarly: `filter[tags]=ruby,rails` splits on commas into `["ruby", "rails"]`. Wrap a value in `{{curlies}}` to prevent comma-splitting (see [Escaping Values](/concepts/resources#escaping-values)).
+
+## Writing to a JSON column {#writing}
+
+There's nothing Graphiti-specific to do here. On a write request, Graphiti coerces the incoming JSON attribute through the `write` type (`strict.hash` or `strict.array` - just a presence/type check) and assigns it to your model via `attributes[:metadata] = value`. Persisting that Ruby `Hash`/`Array` into an actual `jsonb`/`json` column is entirely up to your ORM (ActiveRecord serializes it automatically for `jsonb`/`json` columns) - Graphiti does not serialize to a JSON string itself, so don't do that in your own code either or you'll end up double-encoded.
+
+## Caveats {#caveats}
+
+* `hash` and `array` only support the `eq` filter operator by default - there's no built-in `gt`/`lt`/`prefix` for structured data. Add custom operators yourself if you need them.
+* Non-`single` hash filters always hand your `eq` block an array, even for a single JSON object - a common source of confusion is forgetting the `value[0]` unwrap.
+* There's no schema validation built in - `strict.hash`/`strict.array` just confirm you got a `Hash`/`Array`, not that its keys match anything in particular. For a shape check, register a [custom type](/concepts/resources#custom-types) with `Dry::Types["hash"].schema(...)`.

data/docs/topics/openstruct-models.md

@@ -0,0 +1,50 @@
+---
+title: 'OpenStruct Models'
+---
+
+# OpenStruct Models
+
+[Model Requirements](/concepts/backends-and-models#model-requirements) covers what any Model needs to respond to, and [Usage Without ActiveRecord](/topics/without-activerecord) walks through building a Resource around a PORO. `OpenStruct` satisfies those requirements with zero boilerplate - no `attr_accessor` list, no constructor - which is exactly why Graphiti uses it internally for [remote resources](/topics/remote-resources): `Resource::Remote` and the default `Sideload` model both set `self.model = OpenStruct` (`lib/graphiti/resource/remote.rb`, `lib/graphiti/sideload.rb`), since a remote resource doesn't know its shape ahead of time. That convenience comes with sharp edges if you reach for `OpenStruct` as a model in your own Resources.
+
+## What Graphiti expects from it {#expectations}
+
+Reads go through `@object.send(attribute_name)` (`lib/graphiti/util/serializer_attributes.rb`), and writes go through `model.send(:"#{key}=", value)`-style assignment. `OpenStruct` handles both via `method_missing`, so any attribute you construct it with - or assign later - just works, same as a PORO with `attr_accessor`.
+
+## The gotcha: typos and reserved methods return silently, they don't raise {#gotcha}
+
+An `attr_accessor`-based PORO raises `NoMethodError` the moment you call an undefined reader. `OpenStruct` does not - if the attribute was never set, `#send` on it just returns `nil`:
+
+```ruby
+require "ostruct"
+o = OpenStruct.new(name: "a")
+o.send(:naem)  # => nil, not NoMethodError
+```
+
+Since attribute reads happen inside `@object.send(name_ref)`, a typo'd attribute name (in your `attribute` declaration, or a rename you forgot to propagate) will silently serialize as `null` instead of blowing up in your test suite. With a real PORO the same typo raises immediately and is easy to catch.
+
+Worse, `OpenStruct` only overrides *undefined* methods - if the attribute name collides with something `Object`/`Kernel` already defines, the field is silently swallowed and you get the *original* method's return value instead of your data:
+
+```ruby
+o = OpenStruct.new(hash: 123, count: 5)
+o.hash   # => some large integer (Object#hash), NOT 123
+o.count  # => 5, fine - `count` isn't a reserved method
+```
+
+`id`, `class`, `object_id`, `hash`, `send`, `freeze`, and `to_s` are all real methods on every Ruby object. Naming an attribute after one of them (a `hash` field to store a checksum is a realistic trap given Graphiti's own `:hash` type) won't error - it'll quietly return the wrong value. `id` itself is safe (`Object#id` was removed from modern Ruby in favor of `#object_id`), but don't assume the rest are.
+
+## Validations {#validations}
+
+`OpenStruct` doesn't include `ActiveModel::Validations`, and the [Null adapter's `#save`](/concepts/backends-and-models#model-requirements) only calls `model.valid?` if the model `respond_to?(:valid?)` - so an unvalidated `OpenStruct` model will save "successfully" with no errors payload, not raise. If you want write-request validation, subclass it:
+
+```ruby
+class Employee < OpenStruct
+  include ActiveModel::Validations
+  validates :first_name, presence: true
+end
+```
+
+This works exactly as it would on any other class - `OpenStruct` doesn't get in the way of `include`.
+
+## When it's the right call {#when}
+
+`OpenStruct` is a reasonable choice for throwaway resources, prototypes, and cases like remote resources where the attribute set is genuinely dynamic. For a Resource you're going to maintain, prefer a real PORO, `ActiveModel::Model`, or `Dry::Struct` (all shown in [Model Implementations](/concepts/backends-and-models#model-implementations)) - you get the same zero-ORM flexibility with a class that fails loudly on a mistake instead of quietly serializing `nil`.

data/docs/topics/remote-resources.md

@@ -0,0 +1,291 @@
+---
+title: 'Remote Resources'
+---
+
+## Overview {#overview}
+
+Resources have a defined query contract, and connect together with [Links](/concepts/links). That contract doesn't care whether the sideloaded Resource lives in the same application, so we can point it at a separate service instead:
+
+```ruby
+has_many :comments,
+  remote: 'http://blog-api.com/api/v1/comments'
+```
+
+Splitting an application into services tends to break down at the boundary between them: no consistent query interface, no consistent error handling, no types or backwards-compatibility checks. Graphiti was built to address exactly this - a defined query contract, an errors payload, and a schema with types and backwards-compatibility checks, all organized into RESTful Resources - so cross-service communication is automated rather than hand-rolled per integration.
+
+> Note: Remote Resources are for **read** operations only. The exception
+> is associating to an existing `belongs_to` remote entity.
+
+> Note: We use [Faraday](https://github.com/lostisland/faraday) to hit
+> the remote API. You must add `faraday` to your Gemfile to enable
+> remote resources.
+
+### How it Works {#how-it-works}
+
+Let's take a simple association:
+
+```ruby
+class PostResource < ApplicationResource
+  has_many :comments
+end
+```
+
+This would generate a [Link](/concepts/links) for
+lazy-loading comments:
+
+```ruby
+{
+  related: "http://my-api.com/api/v1/comments?filter[post_id]=123"
+}
+```
+
+Critically, **those same lazy-loading parameters are used when
+eager-loading**:
+
+```ruby
+# under the hood
+posts = PostResource.all.data
+CommentResource.all(filter: { post_id: 123 })
+```
+
+OK, and we also know Resources support [any backend](/concepts/backends-and-models), and we can build an [Adapter](/topics/without-activerecord#adapters) if our backend supports common operations like filtering, sorting, and pagination.
+
+So, that means we can build an Adapter that makes an HTTP request to another Graphiti Resource that lives in a separate API. That adapter is built into Graphiti and comes out-of-the-box: `Graphiti::Adapters::GraphitiAPI`
+
+```ruby
+class CommentResource < ApplicationResource
+  self.remote = "http://my-api.com/api/v1/comments"
+  # under-the-hood, this sets:
+  # self.adapter = Graphiti::Adapters::GraphitiAPI
+end
+```
+
+This Resource works as normal. We can execute queries:
+
+```ruby
+comments = CommentResource.all({
+  sort: '-id',
+  filter: { active: true }
+})
+
+# The model instances are OpenStructs
+comments.data # => [#<OpenStruct>, #<OpenStruct>, ...]
+
+# Those models reflect all the properties returned from the API:
+comments.data.map(&:author) # => ["Jane Doe", "John Doe", ...]
+```
+
+And we can sideload just like we always do:
+
+```ruby
+class PostResource < ApplicationResource
+  # Nothing to see here!
+  has_many :comments
+end
+```
+
+We'll still support Deep Querying - let's fetch the Post and its
+active comments, ordered by `created_at`:
+
+`/posts?include=comments&sort=comments.created_at&filter[active]=true`
+
+Let's say `CommentResource` has an association to `Author`. If `AuthorResource` is defined in the remote API, we can fetch it as normal - no special configuration needed to fetch the `Post`, `Comment`s and `Author`s in a single request.
+
+But maybe only `CommentResource` is remote, and `Authors` are local.
+We need only define the association locally:
+
+```ruby
+class CommentResource < ApplicationResource
+  self.remote = "http://my-api.com/api/v1/comments"
+
+  belongs_to :author
+end
+```
+
+Let's say we need to tweak the display of a property coming from the
+remote API. Again, works just like normal:
+
+```ruby
+class CommentResource < ApplicationResource
+  self.remote = "http://my-api.com/api/v1/comments"
+
+  attribute :body, :string do
+    @object.body.truncate(100)
+  end
+end
+```
+
+You only need to define attributes when overriding this logic -
+otherwise we'll take them directly from the API response. This means you
+don't have to update two repos and coordinate deploys - as soon as you
+add a property to the remote API and deploy it, it will be reflected in
+the local API response.
+
+For the typical use case, we don't even *need* to create this Resource
+class. The sideload definition accepts a `remote:` option, which will
+create a Remote Resource under-the-hood:
+
+```ruby
+class PostResource < ApplicationResource
+  has_many :comments, remote: 'http://my-api.com/api/v1/comments'
+end
+
+# Equivalent to:
+#
+# class PostResource < ApplicationResource
+#   has_many :comments
+# end
+#
+# class CommentResource < ApplicationResource
+#   self.remote = 'http://my-api.com/api/v1/comments'
+# end
+```
+
+> NOTE: When sending a request to a remote API, we request page size
+> `999` so results don't get accidentally cut off. If you need
+> successive requests, please [submit an issue](https://github.com/graphiti-api/graphiti/issues).
+
+### Customizing {#customizing}
+
+We use [Faraday](https://github.com/lostisland/faraday) under-the-hood,
+which allows for various adapters and middleware. In addition:
+
+#### Configure Timeout {#configure-timeout}
+
+```ruby
+class CommentResource < ApplicationResource
+  self.remote = "..."
+
+  # Customize faraday timeout
+  self.timeout = 10
+  self.open_timeout = 20
+end
+```
+
+#### Configure Request {#configure-request}
+
+```ruby
+class CommentResource < ApplicationResource
+  self.remote = "..."
+
+  def make_request(url)
+    # request here is from Faraday:
+    #
+    # conn.get do |req|
+    #   yield req
+    # end
+    #
+    super do |request|
+      request.headers["Custom"] = "Header"
+    end
+  end
+end
+```
+
+#### Configure Headers {#configure-headers}
+
+By default we're going to *forward* the `Authorization` header of the request to the remote API. To override the default headers sent:
+
+```ruby
+# app/resources/comment_resource.rb
+def request_headers
+  { "Some-Foo" => "bar" }
+end
+```
+
+### Error Handling {#error-handling}
+
+If the remote API has an error, we want to re-raise that same error. But
+unless you've enabled [displaying raw errors](/topics/error-handling#displaying-raw-errors), we won't be able to - the only information we have is what's returned from the API.
+
+You're encouraged to display raw errors when an internal or privileged
+user:
+
+```ruby
+rescue_from Exception do |e|
+  handle_exception(e,  show_raw_error: current_user.developer?)
+end
+```
+
+If you do this, we'll be able to re-raise the original error, including
+stacktrace. If raw errors are not enabled, we'll raise whatever
+information is given.
+
+Both styles will be wrapped in `Graphiti::Errors::Remote`, so you can
+differentiate between a local error and a remote one.
+
+## Testing {#testing}
+
+When testing a remote resource, we need to mock the API request and
+response. Graphiti gives you a spec helper to do just that -
+`include_context "remote api"`:
+
+```ruby
+describe 'comments' do
+  include_context 'remote api'
+
+  let(:api_response) do
+    {
+      data: [{
+        id: '1',
+        type: 'comments',
+        attributes: { body: 'hello' }
+      }]
+    }
+  end
+
+  it 'does something' do
+    url = 'http://my-api.com/api/v1/comments?page[size]=999'
+    mock_api(url, api_response)
+    # ... test ...
+  end
+end
+```
+
+This shows all the pieces needed to test remote APIs. We want to test
+
+* The correct URL is hit
+* When given a valid response, the rest of the flow works as expected.
+
+> NOTE: if the remote relationship is a has_many, the API will need to
+> return the foreign key as part of the response. Otherwise, we won't
+> know how to associate these children to their parents.
+
+Here's a slightly longer version, showing that `Post` can sideload `Comment`s:
+
+```ruby
+describe 'sideloading' do
+  describe 'comments' do
+    include_context 'remote api'
+
+    let!(:post) { create(:post) }
+
+    let(:api_response) do
+      {
+        data: [{
+          id: '789',
+          type: 'comments',
+          attributes: { body: 'hello' }
+        }]
+      }
+    end
+
+    before do
+      params[:include] = 'comments'
+    end
+
+    it 'does something' do
+      url = "http://my-api.com/api/v1/comments"
+      url += "?filter[post_id]=#{post_id}"
+      mock_api(url, api_response)
+      render
+      sl = d[0].sideload(:comments)
+      expect(sl.map(&:id)).to eq(['789'])
+      expect(sl.map(&:jsonapi_type).uniq)
+      .to eq(['comments'])
+    end
+  end
+end
+```
+
+> Make sure to include `page[size]=999` in the test URL!