Skip to content

Query-level schema restrictions #300

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 15 commits into from
Oct 27, 2016
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
doc(Warden) document schema masking
  • Loading branch information
rmosolgo committed Oct 27, 2016
commit e8d75f1d7976c96fd1042fd44b7adaac45751fec
61 changes: 61 additions & 0 deletions guides/schema/limiting_visibility.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
---
title: Schema — Limiting Visibility
---

Sometimes, you want to hide schema elements from some users. For example:

- some elements are feature flagged; or
- some elements require higher permissions

If you only want to limit _access_ to these fields, consider the options described in the [authorization guide]({{site.baseurl}}/queries/authorization).

If you want to _completely hide_ some fields, types, enum values or arguments, read on!

## Masking

You can hide parts of the schema by passing `except:` to `Schema.execute`. For example:

```ruby
mask = PermissionMask.new(@current_user)
MySchema.execute(query_string, except: mask)
```

During that query, some elements will be hidden. This means that fields, types, arguments or enum values will be treated as if they were not defined at all.

A mask must respond to `#call(schema_member)`. When that methods returns truthy, the schema member will be hidden.

For example, here's an implementation of `PermissionMask` above:

```ruby
class PermissionMask
def initialize(person)
@person = person
end

# If this returns true, the schema member will be hidden
def call(schema_member)
Permissions.hidden?(person, schema_member)
end
end
```

The `schema_member` may be any of:

- Type ({{ "GraphQL::BaseType" | api_doc }} and subclasses)
- Field ({{ "GraphQL::Field" | api_doc }})
- Argument ({{ "GraphQL::Argument" }} | api_doc }})
- Enum value ({{ "GraphQL::EnumType::EnumValue" | api_doc }})

The result of `#call(schema_member)` is __cached__ during the query.

## Use with Metadata

This feature pairs nicely with attaching custom data to types. See the [types and fields guide]({{ site.baseurl }}/schema/types_and_fields) for information about assigning values to an object's `metadata`.

Then, you can check `metadata` in your mask. For example, to hide fields based on a metadata flag:

```ruby
# Hide secret objects from this user
top_secret = ->(schema_member) { schema_member.metadata[:top_secret]}
MySchema.execute(query_string, except: top_secret)
```