graphdoc-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c92f93cca1793852b9ac3572e5e4ef2f1eedadc0
+  data.tar.gz: 5e986a910e76dbdf1674c20876a502ded8a59d80
+SHA512:
+  metadata.gz: 1711959ac52564a030985dd6c03ed1d8780edeea6e3ca2b40254879b8d2a7f38ac0121305c3cb0a8034c31236f660b155bfb474bbb8bd84aae2aead16bf21b9a
+  data.tar.gz: fb2e8b583548377f59efe1ef5ccf78e3b7a7fcd2e55fbcb06992ecf913ba66740d49c7973fd14c81202b8274dc86276bbc27f9d5c59a2f93a39a8f50c442c41a

data/.gitignore

@@ -0,0 +1,13 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/node_modules/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.rubocop.yml

@@ -0,0 +1,76 @@
+AllCops:
+  Exclude:
+    - 'bin/*'
+    - 'vendor/**/*'
+    - '**/Rakefile'
+    - '**/config.ru'
+    - 'node_modules/**/*'
+  TargetRubyVersion: 2.5
+  DisplayCopNames: true
+
+Performance:
+  Enabled: false
+
+Bundler:
+  Enabled: false
+
+Naming:
+  Enabled: false
+
+Metrics/BlockNesting:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/LineLength:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/ModuleLength:
+  Enabled: false
+
+Style/AsciiComments:
+  Enabled: false
+
+Style/BlockDelimiters:
+  Exclude:
+    - 'spec/**/*'
+
+Style/Documentation:
+  Enabled: false
+
+Style/BlockDelimiters:
+  Enabled: false
+
+Style/DoubleNegation:
+  Enabled: false
+
+Style/GuardClause:
+  Enabled: false
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/SpecialGlobalVars:
+  Enabled: false
+
+Style/NumericPredicate:
+  Enabled: false
+
+Style/Lambda:
+  Enabled: false
+
+Layout/AlignParameters:
+  EnforcedStyle: with_fixed_indentation
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
+Lint/AmbiguousRegexpLiteral:
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.3.5
+before_install: gem install bundler -v 1.15.4

data/Gemfile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in graphdoc-ruby.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 alpaca-tc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,202 @@
+# Graphdoc::Ruby
+
+Mountable [graphdoc](https://github.com/2fd/graphdoc) based on rack.
+graphdoc is static page generator for documenting GraphQL Schema.
+
+<img width="1169" alt="screen" src="https://user-images.githubusercontent.com/1688137/34389782-11c80450-eb7f-11e7-8b83-fdfbcbfa711e.png">
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'graphdoc-ruby'
+```
+
+Install graphdoc to your machine:
+
+```sh
+$ npm install -g @2fd/graphdoc
+
+OR
+
+$ yarn add @2fd/graphdoc
+```
+
+## Usage
+
+### In pure rack application
+
+```ruby
+# config.ru
+
+require 'graphdoc_ruby'
+
+GraphdocRuby.configure do |config|
+  # endpoint of GraphQL
+  config.endpoint = 'https://graphql-pokemon.now.sh/'
+end
+
+run(GraphdocRuby::Application)
+```
+
+```sh
+$ gem install rack
+$ bundle exec rackup
+```
+
+### In rails application
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  mount GraphdocRuby::Application, at: 'graphdoc'
+end
+
+# config/initializers/graphdoc.rb
+GraphdocRuby.configure do |config|
+  config.endpoint = 'https://graphql-pokemon.now.sh/'
+end
+```
+
+```sh
+$ bundle exec rails server --port 3000
+$ open http://0.0.0.0:3000/graphdoc
+```
+
+## Configuration
+
+```ruby
+GraphdocRuby.configure do |config|
+  # :endpoint
+  #
+  # Required: <String>
+  # GraphQL endpoint url or dumped schema.json path.
+  # 
+  # Example
+  #   config.endpoint = 'https://your-application.com/graphql'
+  #   config.endpoint = Rails.root.join('tmp', 'graphql', 'schema.json')
+
+  # :executable_path
+  #
+  # Optional: <String>
+  # Executable path of `graphdoc`.
+  # (default: `Bundler.which('graphdoc')`)
+  #
+  # Example
+  #   config.executable_path = Rails.root.join('node_modules', '.bin', 'graphdoc')
+
+  # :output_directory
+  #
+  # Optional: <String>
+  # Output path for `graphdoc`. If you disabled run_time_generation, this value must be customized.
+  # NOTE: Do not assign private directory because output_directory folders are served via rack application.
+  # (default: `File.join(Dir.mktmpdir, 'graphdoc')`)
+  #
+  # Example
+  #   config.output_directory = Rails.root.join('tmp', 'graphdoc')
+
+  # :overwrite
+  # Optional: <Boolean>
+  # Overwrite files if generated html already exist.
+  # (default: true)
+  #
+  # Example
+  #   config.overwrite = false
+
+  # :run_time_generation
+  # Optional: <Boolean>
+  # Generate html with graphdoc on the first access.
+  # (default: true)
+  # 
+  # Example
+  #   config.run_time_generation = Rails.env.development?
+
+  # :graphql_context
+  #
+  # Optional: <Proc>
+  # Context of your graphql.
+  # (default: -> {})
+  #   config.graphql_context = -> { { 'Authorization' => "Token #{ENV['GITHUB_ACCESS_TOKEN']}", 'User-Agent' => 'graphdoc-client' } }
+
+  # :graphql_query
+  #
+  # Optional: <Proc>
+  # Query of your graphql.
+  # (default: -> {})
+  #   config.graphql_query = -> { { 'token' => ENV['SECRET_API_TOKEN'] } }
+
+  # ===
+  # Integrated with [graphql-ruby](https://github.com/rmosolgo/graphql-ruby)
+  # ===
+  #
+  # :schema_name
+  #
+  # Optional: <String>
+  # Schema name of your graphql-ruby. It is necessary when generating schema.json.
+  # (default: nil)
+  #
+  # Example
+  #   config.schema_name = 'MyApplicationSchema'
+end
+```
+
+### Example Configuration
+
+#### Github
+
+```ruby
+GraphdocRuby.configure do |config|
+  # Github
+  config.endpoint = 'https://api.github.com/graphql'
+
+  config.graphql_context = -> {
+    {
+      'Authorization' => "bearer #{ENV['GITHUB_ACCESS_TOKEN']}",
+      'User-Agent' => 'my-client',
+    }
+  }
+end
+```
+
+#### Your Rails product
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  namespace :admin do
+    mount GraphdocRuby::Application, at: 'graphdoc'
+  end
+end
+
+# config/initializers/graphdoc.rb
+GraphdocRuby.configure do |config|
+  config.endpoint = Rails.root.join('tmp', 'graphql', 'schema.json')
+  config.output_directory = Rails.root.join('tmp', 'graphdoc').to_s
+  config.schema_name = 'MyApplicationSchema'
+  config.run_time_generation = Rails.env.development?
+end
+
+# Capfile
+namespace :deploy do
+  after :generate_graphdoc do
+    within release_path do
+      # Generate schema.json from MyApplicationSchema
+      execute :rake, 'graphdoc:dump_schema'
+
+      # Generate html with graphdoc from schema.json
+      execute :rake, 'graphdoc:generate'
+    end
+  end
+
+  after :publishing, :generate_graphdoc
+end
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/alpaca-tc/graphdoc-ruby.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require 'graphdoc-ruby/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+GraphdocRuby::RakeTask.new
+
+task :default => :spec

data/config.ru

@@ -0,0 +1,17 @@
+require 'graphdoc_ruby'
+
+GraphdocRuby.configure do |config|
+  # Pokemon
+  config.endpoint = 'https://graphql-pokemon.now.sh/'
+
+  # Github
+  # config.endpoint = 'https://api.github.com/graphql'
+  # config.graphql_context = -> {
+  #   {
+  #     'Authorization' => "bearer XXXXXXX",
+  #     'User-Agent' => 'my-client',
+  #   }
+  # }
+end
+
+run(GraphdocRuby::Application)

data/graphdoc-ruby.gemspec

@@ -0,0 +1,33 @@
+
+# frozen_string_literal: true
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'graphdoc-ruby/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'graphdoc-ruby'
+  spec.version       = GraphdocRuby::VERSION
+  spec.authors       = ['alpaca-tc']
+  spec.email         = ['alpaca-tc@alpaca.tc']
+
+  spec.summary       = 'Static page rack application for documenting GraphQL Schema'
+  spec.description   = 'Static page rack application for documenting GraphQL Schema'
+  spec.homepage      = 'https://github.com/alpaca-tc/graphdoc-ruby'
+  spec.license       = 'MIT'
+
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'activesupport', '>= 4.2.0'
+  spec.add_dependency 'bundler'
+  spec.add_dependency 'rack'
+
+  spec.add_development_dependency 'pry'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'rubocop'
+end

data/lib/graphdoc-ruby.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative './graphdoc_ruby'

data/lib/graphdoc-ruby/application.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'rack/response'
+
+module GraphdocRuby
+  class Application
+    Semaphore = Mutex.new
+
+    def self.call(env)
+      @application ||= new
+      @application.call(env)
+    end
+
+    def self.graphdoc
+      config = GraphdocRuby.config
+      config.assert_configuration!
+
+      GraphdocRuby::Graphdoc.new(
+        output: config.output_directory,
+        executable: config.executable_path,
+        endpoint: config.endpoint,
+        overwrite: config.overwrite,
+        mtime: config.mtime,
+        query: config.evaluate_graphql_query,
+        context: config.evaluate_graphql_context
+      )
+    end
+
+    def initialize
+      generate_html if GraphdocRuby.config.run_time_generation
+
+      @static = GraphdocRuby::Static.new(GraphdocRuby.config.output_directory)
+    end
+
+    def call(env)
+      serve_static_file(env) || not_found
+    end
+
+    private
+
+    def generate_html
+      Semaphore.synchronize do
+        if should_generate_schema_json?
+          GraphdocRuby::GraphqlJson.write_schema_json
+        end
+
+        self.class.graphdoc.generate_document!
+      end
+    end
+
+    def should_generate_schema_json?
+      !GraphdocRuby::Utils.valid_url?(GraphdocRuby.config.endpoint) && !GraphdocRuby::Utils.file_exist?(GraphdocRuby.config.endpoint)
+    end
+
+    def not_found
+      if GraphdocRuby.config.run_time_generation
+        [404, { 'Content-Type' => 'text/html' }, ['Not found generated html']]
+      else
+        [404, { 'Content-Type' => 'text/html' }, ['Not found generated html. Please run `rake graphdoc:generate`']]
+      end
+    end
+
+    def serve_static_file(env)
+      request = Rack::Request.new(env)
+      return unless request.get? || request.head?
+      return redirect_to_slash_path(env) if html_access_without_slash?(env)
+
+      path = request.path_info.chomp('/')
+      match = @static.match?(path)
+
+      if match
+        request.path_info = match
+        @static.serve(request)
+      end
+    end
+
+    def html_access_without_slash?(env)
+      original_path = env[Rack::REQUEST_PATH]
+      File.extname(original_path).empty? && !original_path.end_with?('/')
+    end
+
+    # Unfortunately, html generated by graphdoc contains relative path.
+    def redirect_to_slash_path(env)
+      path = env[Rack::REQUEST_PATH] + '/'
+
+      response = Rack::Response.new
+      response.redirect(path)
+      response.finish
+    end
+  end
+end