ed_fi_client 0.1.0

data/lib/ed_fi/client/auth.rb

@@ -0,0 +1,99 @@
+require 'crapi'
+require 'json'
+
+require 'ed_fi/client/access_token'
+require 'ed_fi/client/errors'
+
+class EdFi::Client < Crapi::Client
+  ## The {EdFi::Client::Auth EdFi::Client::Auth} represents a complete authentication *mechanism*
+  ## that makes the necessary calls for authorization codes and access tokens, keeps track of any
+  ## token generated, and re-requests new tokens as necessary based on the existing token's
+  ## lifecycle.
+  ##
+  ##
+  class Auth
+    ## The URI to request an authorization code.
+    AUTHORIZATION_CODE_URI = '/oauth/authorize'.freeze
+
+    ## The MIME content type to use for authorization code requests.
+    AUTHORIZATION_CODE_CONTENT_TYPE = 'application/x-www-form-urlencoded'.freeze
+
+    ## The URI to request an access token.
+    ACCESS_TOKEN_URI = '/oauth/token'.freeze
+
+    ## The MIME content type to use for access token requests.
+    ACCESS_TOKEN_CONTENT_TYPE = 'application/json'.freeze
+
+    ## @param client [Crapi::Client]
+    ##   The client to use for making auth calls.
+    ##
+    ## @param client_id [String]
+    ##   The client id to use for authentication. This is AKA the "api key" / "username".
+    ##
+    ## @param client_secret [String]
+    ##   The client secret to use for authentication. This is AKA the "api secret" / "password".
+    ##
+    def initialize(client:, client_id:, client_secret:)
+      @client = client
+      @client_id = client_id
+      @client_secret = client_secret
+
+      @access_token = nil
+    end
+
+    ## Gives an access token string that is guaranteed to be valid for *at least* 5 seconds.
+    ##
+    ## Note a new token is requested and returned if the existing token is no longer valid.
+    ##
+    ##
+    ## @return [String]
+    ##
+    def token
+      @access_token = new_access_token unless @access_token&.valid?
+      @access_token.token
+    end
+
+    ##
+
+    private
+
+    ##
+
+    ## Requests and yields a new authorization *code".
+    ##
+    ##
+    ## @raise [EdFi::Client::UnableToAuthenticateError]
+    ##
+    ## @return [String]
+    ##
+    def new_authorization_code
+      auth = @client.post(
+        AUTHORIZATION_CODE_URI,
+        payload: { Client_id: @client_id, Response_type: 'code' },
+        headers: { 'Content-Type': AUTHORIZATION_CODE_CONTENT_TYPE }
+      )
+      raise EdFi::Client::UnableToAuthenticateError, 'Failed to fetch authorization code.' unless auth&.key? :code
+
+      auth[:code]
+    end
+
+    ## Requests and yields a new access *token*.
+    ##
+    ##
+    ## @raise [EdFi::Client::UnableToAuthenticateError]
+    ##
+    ## @return [EdFi::Client::AccessToken]
+    ##
+    def new_access_token
+      auth = @client.post(
+        ACCESS_TOKEN_URI,
+        payload: { Client_id: @client_id, Client_secret: @client_secret,
+                   Code: new_authorization_code, Grant_type: 'authorization_code' },
+        headers: { 'Content-Type': ACCESS_TOKEN_CONTENT_TYPE }
+      )
+      raise EdFi::Client::UnableToAuthenticateError, 'Failed to fetch access token.' unless auth&.key? :access_token
+
+      EdFi::Client::AccessToken.new(auth)
+    end
+  end
+end

data/lib/ed_fi/client/errors.rb

@@ -0,0 +1,19 @@
+require 'crapi'
+
+class EdFi::Client < Crapi::Client
+  ## The base Error class for all {EdFi::Client}-related issues.
+  ##
+  class Error < ::StandardError
+  end
+
+  ## An error relating to missing, invalid, or incompatible method arguments.
+  ##
+  class ArgumentError < Error
+  end
+
+  ## An error relating to a bad request for an authorization *code* or access *token*. This is most
+  ## likely due to a connectivity issue, a bad base URI in the given client, or invalid credentials.
+  ##
+  class UnableToAuthenticateError < Error
+  end
+end

data/lib/ed_fi/client/proxy.rb

@@ -0,0 +1,65 @@
+require 'crapi'
+
+class EdFi::Client < Crapi::Client
+  ## The Crapi::Proxy to {EdFi::Client}'s Crapi::Client.
+  ##
+  ## An {EdFi::Client::Proxy EdFi::Client::Proxy} calls {EdFi::Client::Response#client= #client=}
+  ## on every CRUD-method-generated {EdFi::Client::Response EdFi::Client::Response}.
+  ##
+  class Proxy < Crapi::Proxy
+    ## CRUD method: GET
+    ##
+    ## All parameters are passed directly through to Crapi::Proxy#get.
+    ##
+    def get(*args)
+      response = super
+      response.client = self
+
+      response
+    end
+
+    ## CRUD method: DELETE
+    ##
+    ## All parameters are passed directly through to Crapi::Proxy#delete.
+    ##
+    def delete(*args)
+      response = super
+      response.client = self
+
+      response
+    end
+
+    ## CRUD method: POST
+    ##
+    ## All parameters are passed directly through to Crapi::Proxy#post.
+    ##
+    def post(*args)
+      response = super
+      response.client = self
+
+      response
+    end
+
+    ## CRUD method: PATCH
+    ##
+    ## All parameters are passed directly through to Crapi::Proxy#patch.
+    ##
+    def patch(*args)
+      response = super
+      response.client = self
+
+      response
+    end
+
+    ## CRUD method: PUT
+    ##
+    ## All parameters are passed directly through to Crapi::Proxy#put.
+    ##
+    def put(*args)
+      response = super
+      response.client = self
+
+      response
+    end
+  end
+end

data/lib/ed_fi/client/response.rb

@@ -0,0 +1,150 @@
+require 'crapi'
+
+class EdFi::Client < Crapi::Client
+  ## Represents an API response. {EdFi::Client::Response EdFi::Client::Response} instances
+  ## initialized from a Hash also allow for reference chaining.
+  ##
+  class Response
+    ## @param response [Hash, Array]
+    ##   The value to encapsulate as an {EdFi::Client::Response EdFi::Client::Response}.
+    ##
+    ## @param client [Crapi::Client]
+    ##   The client to use for request chaining.
+    ##
+    ##
+    ## @raise [EdFi::Client::ArgumentError]
+    ##
+    def initialize(response, client: nil)
+      @client = client
+
+      case response
+      when Hash
+        @response = response.to_a.map do |tuple|
+          (key, value) = tuple.dup
+          key = key.to_s.underscore.to_sym
+          value = EdFi::Client::Response.new(value, client: @client) if value.is_a?(Hash) || value.is_a?(Array)
+
+          [key, value]
+        end.to_h.with_indifferent_access
+
+      when Array
+        @response = response.dup.map do |i|
+          i = EdFi::Client::Response.new(i, client: @client) if i.is_a?(Hash) || i.is_a?(Array)
+          i
+        end
+
+      when nil, ''
+        ## This can happen for non-body-returning calls.
+        @response = {}.with_indifferent_access
+
+      else
+        raise EdFi::Client::ArgumentError, %(Unexpected "response" type: #{response.class})
+
+      end
+    end
+
+    ## Deep updates the associated Crapi::Client] for this and all descendant
+    ## {EdFi::Client::Response EdFi::Client::Response} instances.
+    ##
+    def client=(client)
+      @client = client
+
+      case @response
+      when Hash
+        @response.values.each { |i| i.client = client if i.is_a? EdFi::Client::Response }
+
+      when Array
+        @response.each { |i| i.client = client if i.is_a? EdFi::Client::Response }
+
+      end
+    end
+
+    ## @private
+    ##
+    def to_s
+      @response.to_s
+    end
+
+    ## @private
+    ##
+    def inspect
+      @response.inspect
+    end
+
+    ## rubocop:disable Security/Eval
+    ##
+    ## We're running `eval` on the `#to_s` of a built-in type, which is safe.
+    ## Attempting to let `#as_json` run on its own results in a stack overflow.
+
+    ## @private
+    ##
+    def as_json
+      eval(to_s).as_json
+    end
+    ## rubocop:enable Security/Eval
+
+    ## rubocop:disable Security/Eval
+    ##
+    ## We're running `eval` on the `#to_s` of a built-in type, which is safe.
+    ## Attempting to let `#to_json` run on its own results in a stack overflow.
+
+    ## @private
+    ##
+    def to_json
+      eval(to_s).to_json
+    end
+    ## rubocop:enable Security/Eval
+
+    ## rubocop:disable Style/MethodMissing, Metrics/BlockNesting, Metrics/PerceivedComplexity
+
+    ## @private
+    ##
+    def method_missing(name, *args, &block)
+      ## Note references are cached.
+      ## To force a refresh on an already-cached reference,
+      ## the method should be called with a single `true` parameter.
+      ## (i.e. `#school` vs `#school(true)`)
+
+      if @response.is_a? Hash
+        ## Allow for acceess to response values via dot notation.
+        return @response[name] if @response.key? name
+
+        ## Allow for assignment to response values via dot notation.
+        return @response.send(:'[]=', name[0...-1], *args, &block) if name.to_s.ends_with? '='
+
+        ## Allow for simple access to referenced resources.
+        if @client.present?
+          @references ||= {}
+          reference = @response["#{name}_reference"].link.href rescue nil
+
+          if reference.present?
+            @references.delete(reference) if args[0] == true
+            return @references[reference] ||= @client.get(reference)
+          end
+        end
+      end
+
+      ## All other unaccounted-for method calls should be delegated to the response Hash/Array.
+      @response.send(name, *args, &block)
+    end
+    ## rubocop:enable Style/MethodMissing, Metrics/BlockNesting, Metrics/PerceivedComplexity
+
+    ## @private
+    ##
+    def respond_to_missing?(name, include_private = false)
+      ( \
+        ( \
+          (@response.is_a? Hash) \
+          && \
+          ( \
+            @response.key?(name) \
+            || \
+            @response.key?("#{name}_reference".to_sym) \
+          ) \
+        ) \
+        || \
+        @response.respond_to?(name, include_private) \
+      )
+    end
+  end
+end

data/lib/ed_fi/client/version.rb

@@ -0,0 +1,18 @@
+require 'crapi'
+
+## Note we're explicitly declaring "EdFi" as a module here so this file can be directly require'd
+## from the base gemspec without issues.
+
+## The EdFi module houses the {EdFi::Client EdFi::Client} in this gem, but should also house future
+## EdFi tooling.
+##
+module EdFi
+  class Client < Crapi::Client
+    ## The canonical **ed_fi_client** gem version.
+    ##
+    ## This should only ever be updated *immediately* before a release; the commit that updates this
+    ## value should be pushed **by** the `rake release` process.
+    ##
+    VERSION = '0.1.0'.freeze
+  end
+end

data/lib/ed_fi_client.rb

@@ -0,0 +1 @@
+require 'ed_fi/client'

metadata

@@ -0,0 +1,201 @@
+--- !ruby/object:Gem::Specification
+name: ed_fi_client
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nestor Custodio
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2018-05-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec_junit_formatter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.2.0
+- !ruby/object:Gem::Dependency
+  name: crapi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+description: 
+email:
+- sakimorix@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".ruby-version"
+- ".travis.yml"
+- ".yardopts"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- docs/EdFi.html
+- docs/EdFi/Client.html
+- docs/EdFi/Client/AccessToken.html
+- docs/EdFi/Client/ArgumentError.html
+- docs/EdFi/Client/Auth.html
+- docs/EdFi/Client/Error.html
+- docs/EdFi/Client/Proxy.html
+- docs/EdFi/Client/Response.html
+- docs/EdFi/Client/UnableToAuthenticateError.html
+- docs/_index.html
+- docs/class_list.html
+- docs/css/common.css
+- docs/css/full_list.css
+- docs/css/style.css
+- docs/file.README.html
+- docs/file_list.html
+- docs/frames.html
+- docs/index.html
+- docs/js/app.js
+- docs/js/full_list.js
+- docs/js/jquery.js
+- docs/method_list.html
+- docs/top-level-namespace.html
+- ed_fi_client.gemspec
+- lib/ed_fi/client.rb
+- lib/ed_fi/client/access_token.rb
+- lib/ed_fi/client/auth.rb
+- lib/ed_fi/client/errors.rb
+- lib/ed_fi/client/proxy.rb
+- lib/ed_fi/client/response.rb
+- lib/ed_fi/client/version.rb
+- lib/ed_fi_client.rb
+homepage: https://www.github.com/nestor-custodio/ed_fi_client
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: A simple API wrapper for Ed-Fi ODS access.
+test_files: []