better_heroku 0.0.1 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7bee66aa4746a36e226976943195c0f108919bda
-  data.tar.gz: b656652bfff3acdcc4774231a2b4267bd0ed0a6e
+  metadata.gz: bac3f1445e96dca5b8ca16e11806e359a60d84df
+  data.tar.gz: 119a7513c5cc7704a2962aefad18ccaa121224dd
 SHA512:
-  metadata.gz: d4f92d4b7fa0014e40893157685dcdff329a3a35603b7286b319dbabf2218a04f0388c1597aba625c9c4d4950cbcfdccde54f5a461eaa2679a1881e0d7dc1000
-  data.tar.gz: fdf5ec34f75875816ec02e6d207c9f0af1250df73fc7f15d52357772570e89db934baf9a2415dba9062bf7bb6c0352813f830563851d5144207ff380a81d1b55
+  metadata.gz: 210ad08b4e73ebd61b94af67f1537d314ca774eae9a73ba53709495003dd3e26d5fffc9be8a50f9e38a5dfccba13712272456a97cee2f73179e24eacc4d59d32
+  data.tar.gz: ddb9f5260b9614091f3d8e7da095eee456a48934921838d1e4baf16f34fa9729638f0778961b68b7984aef05c652238e59685d7cbe2b1688c649f70215c81c9e

data/README.md

@@ -26,22 +26,30 @@
 
 # Features
 
-**BetterHeroku** Is a better Heroku client gem. The official "platform-api" Heroku client gem has several issues:
+**BetterHeroku** Is a better Heroku client gem. The official "platform-api"
+Heroku client gem has several issues:
 
- * The name itself is presumptuous. No mention of Heroku, assumes there's no other platform for which there's an API.
- * The code is auto-generated from a `schema.json` provided by Heroku themselves. The gem is not updated nearly as
+ * The name itself is presumptuous. No mention of Heroku, assumes there's no
+   other platform for which there's an API.
+ * The code is auto-generated from a `schema.json` provided by Heroku
+   themselves. The gem is not updated nearly as
    frequently as the `schema.json`, and lags behind the published APIs.
- * The `schema.json` itself often lags behind the published API docs, and occasionally disagrees with them.
+ * The `schema.json` itself often lags behind the published API docs, and
+   occasionally disagrees with them.
  * It's not obvious how to consume the documented API.
-   * The way to get the [current account][heroku-account-info] is `heroku.account.info("~")`. The only way to know this
+   * The way to get the [current account][heroku-account-info] is
+     `heroku.account.info("~")`. The only way to know this
      is to contact Heroku support.
-   * For a url with multiple parameters, like [info for a dyno for an app][heroku-dyno-info], is requested like
-     `heroku.dyno.info(app, dyno)`. The parameters are not documented, because the code is generated.
- * The client provides no access to the lower-level HTTP client, Excon, to enable features such as HTTP persistence, or
-   to override it for testing.
- * The client provides no means to add logging or instrumentation of the raw requests.
+   * For a url with multiple parameters, like [info for a dyno for an app][heroku-dyno-info],
+     is requested like `heroku.dyno.info(app, dyno)`.
+     The parameters are not documented, because the code is generated.
+ * The client provides no access to the lower-level HTTP client, Excon, to
+   enable features such as HTTP persistence, or to override it for testing.
+ * The client provides no means to add logging or instrumentation of the raw
+   requests.
 
-**BetterHeroku** attempts to solve all these problems by being a much simpler and less-opinionated implementation.
+**BetterHeroku** attempts to solve all these problems by being a much simpler
+and less-opinionated implementation.
 
 [heroku-account-info]: https://devcenter.heroku.com/articles/platform-api-reference#account
 [heroku-dyno-info]:    https://devcenter.heroku.com/articles/platform-api-reference#dyno-info
@@ -67,10 +75,11 @@ resp.status #=> 200
 resp["id"]  #=> "01234567-89ab-cdef-0123-456789abcdef"
 ```
 
-The client pays no attention to the segments of the url passed in, and instead just joins them with `/`. This way, it
-always matches 1:1 with the published API docs. In this example, we're using the [App Info][heroku-app-info] endpoint,
-which looks like `GET /apps/{app_id_or_name}` in the docs. Just pass in the various segments in the same order, and
-it'll work.
+The client pays no attention to the segments of the url passed in, and instead
+just joins them with `/`. This way, it always matches 1:1 with the published
+API docs. In this example, we're using the [App Info][heroku-app-info]
+endpoint, which looks like `GET /apps/{app_id_or_name}` in the docs. Just pass
+in the various segments in the same order, and it'll work.
 
 [heroku-app-info]: https://devcenter.heroku.com/articles/platform-api-reference#app-info
 
@@ -91,21 +100,23 @@ client = BetterHeroku::Client.new.authenticate(token: "01234567-89ab-cdef-0123-4
 resp = client.get("apps", app_id)
 ```
 
-In one-off scripts this is fine, but for production usage I strongly recommend you put the token in a config or
-environment variable.
+In one-off scripts this is fine, but for production usage I strongly recommend
+you put the token in a config or environment variable.
 
 ### OAuth tokens
 
-When making requests on behalf of other users, you'll need to use OAuth tokens. See the
-[Heroku OAuth docs][heroku-oauth-docs] for details.
+When making requests on behalf of other users, you'll need to use OAuth tokens.
+See the [Heroku OAuth docs][heroku-oauth-docs] for details.
 
-Once set up, you'll have your Heroku OAuth secret. In this example, we've stored it in an environment variable called
-`HEROKU_OAUTH_SECRET`. Once your users go through the web flow, you'll get back from Heroku a `token` and a
-`refresh_token`. The `token` expires after 8 hours, and the `refresh_token` never expires, and may be used to obtain a
-new token.
+Once set up, you'll have your Heroku OAuth secret. In this example, we've
+stored it in an environment variable called `HEROKU_OAUTH_SECRET`. Once your
+users go through the web flow, you'll get back from Heroku a `token` and a
+`refresh_token`. The `token` expires after 8 hours, and the `refresh_token`
+never expires, and may be used to obtain a new token.
 
-If you're not concerned about storing the token (perhaps you only make a few requests once a day, and the token would
-have expired the next time you need it anyways), you can just authenticate with your secret and the refresh token:
+If you're not concerned about storing the token (perhaps you only make a few
+requests once a day, and the token would have expired the next time you need it
+anyways), you can just authenticate with your secret and the refresh token:
 
 ```ruby
 client = BetterHeroku::Client.new
@@ -114,27 +125,38 @@ authenticated_client = client.oauth(secret: ENV["HEROKU_OAUTH_SECRET"], refresh_
 resp = authenticated_client.get("apps", app_id)
 ```
 
-The `authenticated_client` will automatically handle refreshing the oauth token, and making requests using that. In the
-unlikely situation where that object lives longer than the token expiry, it will automatically refresh again as needed.
+The `authenticated_client` will not automatically handle refreshing the oauth
+token, however it does provide a simple facility to do so via
+`#refresh_oauth_token`. Additionally, that method takes an optional callback
+that can be used to persist the access token for future requests.
 
-Alternatively, the `authenticated_client` provides a callback that gets called when the refresh happens, which you can use
-to persist the token for future requests:
+As **BetterHeroku** borrow's HTTP.rb's philosophy of a immutable client object,
+you'll need to replace the client you're using with the refreshed client
+object. If you're using threads, its on you to handle handle that in a
+threadsafe manner. In most cases, doing so probably isn't necessary, the
+following example should work fine.
 
 ```ruby
-authenticated_client.on_token_refresh do |response|
-  user.update_attribute(:oauth_token, response["access_token"])
+response = authenticated_client.get("apps", app_id)
+if response.status == 401
+  refreshed_client = authenticated_client.refresh_oauth_token do |response|
+    user.update_attribute(:oauth_token, response["access_token"])
+  end
+  response = refreshed_client.get("apps", app_id)
 end
 ```
 
-The `response` is the response body as documented in the [Heroku OAuth token refresh docs][heroku-token-refresh-docs].
+The `response` is the response body as documented in the [Heroku OAuth token
+refresh docs][heroku-token-refresh-docs].
 
 [heroku-oauth-docs]: https://devcenter.heroku.com/articles/oauth
 [heroku-token-refresh-docs]: https://devcenter.heroku.com/articles/oauth#token-refresh
 
 ## Mocking requests
 
-You probably don't want to always make actual requests against the Heroku API, so **BetterHeroku** provides a mechanism
-to pass in the lower HTTP client. An example of what this might look like:
+You probably don't want to always make actual requests against the Heroku API,
+so **BetterHeroku** provides a mechanism to pass in the lower HTTP client. An
+example of what this might look like:
 
 ```ruby
 let(:http) { double(HTTP) }
@@ -149,7 +171,8 @@ it "should do awesome things" do
 end
 ```
 
-Also, be sure to check out the [FakeHTTP][fake-http] gem to mock the HTTP library with a Sinatra-like DSL.
+Also, be sure to check out the [FakeHTTP][fake-http] gem to mock the HTTP
+library with a Sinatra-like DSL.
 
 [fake-http]: https://github.com/paul/fake_http
 

data/lib/better_heroku/client.rb

@@ -1,29 +1,84 @@
 require "http"
 
+require "better_heroku/oauth_handler"
+require "better_heroku/response"
+require "better_heroku/null_instrumenter"
+
 module BetterHeroku
   class Client
     ACCEPT = "application/vnd.heroku+json; version=3"
+    DEFAULT_HEADERS = {
+      "Accept" => ACCEPT
+    }
 
-    attr_reader :host, :http
+    API_HOST  = "https://api.heroku.com"
 
-    def initialize(host: "https://api.heroku.com", http: HTTP)
-      @host = host
-      @http = http.headers("Accept" => ACCEPT)
+    def initialize(host: "https://api.heroku.com", http: HTTP, instrumenter: BetterHeroku::NullInstrumenter.new, **kwargs)
+      @options = kwargs
+      @options[:host] = host
+      @options[:http] = http.headers(DEFAULT_HEADERS)
+      @options[:instrumenter] = instrumenter
     end
 
-    def get(*parts)
-      path = [host, *parts].join("/")
-      http.get(path)
+    def get(*parts, **options)
+      request(:get, *parts, **options)
+    end
+
+    def post(*parts, **options)
+      request(:post, *parts, **options)
+    end
+
+    def put(*parts, **options)
+      request(:post, *parts, **options)
+    end
+
+    def delete(*parts, **options)
+      request(:post, *parts, **options)
+    end
+
+    def patch(*parts, **options)
+      request(:post, *parts, **options)
+    end
+
+    def authenticate(token:)
+      branch http: http.auth("Bearer #{token}")
     end
 
-    def authenticate(token: token)
-      branch http.auth("Bearer #{token}")
+    def oauth(secret:, refresh_token:, access_token: nil)
+      oauth_handler =
+        OAuthHandler.new(secret: secret, refresh_token: refresh_token)
+      branch(oauth_handler: oauth_handler).authenticate(token: access_token)
+    end
+
+    def refresh_oauth_token(&block)
+      access_token = @options[:oauth_handler].refresh_token(&block)
+
+      authenticate(token: access_token)
     end
 
     private
 
-    def branch(http)
-      self.class.new http: http
+    def request(verb, *parts, **options)
+      path = [host, *parts].join("/")
+      instrument(verb, path, options) do |payload|
+        Response.new(http.request(verb, path, options)).tap { |resp| payload[:response] = resp }
+      end
+    end
+
+    def host
+      @options[:host]
+    end
+
+    def http
+      @options[:http]
+    end
+
+    def branch(options)
+      self.class.new @options.merge(options)
+    end
+
+    def instrument(verb, url, options, &block)
+      @options[:instrumenter].instrument("request.better_heroku_client", verb: verb, url: url, options: options, &block)
     end
   end
 end

data/lib/better_heroku/identity.rb

@@ -12,7 +12,7 @@ module BetterHeroku
     end
 
     def self.version
-      "0.0.1"
+      "0.1.1"
     end
 
     def self.version_label

data/lib/better_heroku/null_instrumenter.rb

@@ -0,0 +1,12 @@
+module BetterHeroku
+  class NullInstrumenter
+
+    def initialize
+    end
+
+    def instrument(name, payload = {})
+      yield payload if block_given?
+    end
+  end
+end
+

data/lib/better_heroku/oauth_handler.rb

@@ -0,0 +1,30 @@
+
+module BetterHeroku
+  class OAuthHandler
+    AUTH_HOST = "https://id.heroku.com"
+
+    def initialize(secret:, refresh_token:, client: BetterHeroku::Client)
+      @secret = secret
+      @refresh_token = refresh_token
+
+      @client = client.new(host: AUTH_HOST)
+    end
+
+    def refresh_token(&callback)
+      response = @client.post("oauth/token", params: params)
+      callback.call(response) if block_given?
+
+      response["access_token"]
+    end
+
+    private
+
+    def params
+      {
+        grant_type: "refresh_token",
+        refresh_token: @refresh_token,
+        client_secret: @secret
+      }
+    end
+  end
+end

data/lib/better_heroku/response.rb

@@ -0,0 +1,17 @@
+
+module BetterHeroku
+  class Response
+    extend Forwardable
+
+    attr_reader :http_response
+
+    delegate %i[parse status ] => :http_response
+
+    delegate %i[[] each map] => :parse
+
+    def initialize(http_response)
+      @http_response = http_response
+    end
+
+  end
+end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: better_heroku
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.1
 platform: ruby
 authors:
 - Paul Sadauskas
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-02-03 00:00:00.000000000 Z
+date: 2017-02-16 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -150,6 +164,9 @@ files:
 - lib/better_heroku.rb
 - lib/better_heroku/client.rb
 - lib/better_heroku/identity.rb
+- lib/better_heroku/null_instrumenter.rb
+- lib/better_heroku/oauth_handler.rb
+- lib/better_heroku/response.rb
 homepage: https://github.com/paul/better_heroku
 licenses:
 - MIT