issue 0.0.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 29925e2f5c0b58136fe7097671b9577766034701c97aeb78fc9999a8fb4e23ee
-  data.tar.gz: 54d441c401a125e0e0ebea5baa48ead70dc3dcd5ad4a49c660673a4c626e3e07
+  metadata.gz: 9a0d24902085e9ef25c6765748362b06f5015bbd88848db03513c0cd7f33ce9c
+  data.tar.gz: '099f1cce4e61d95ab0ca87a6c057f59c5b4bae50e2b59cca25df9e334d3b1c39'
 SHA512:
-  metadata.gz: 495c6477690e7bc7c688876ac242bb7884f87c9746dcc3ba6e0e2b8cbd8a012a758afcf07a2ef9f09b1a9280afac97a255a317fdcbfabb4668860a442dd04f37
-  data.tar.gz: 688bb57f456b5831a0840d8ad847bcd24a11baf42e43c09b1fe66fd2ae5292088da86aef45075c3c5025e39e792f51dff5d73594f7fea7f9a1d4605a2c05a0f2
+  metadata.gz: d5a4bcfa1cb46b5b6a78184e235743cc846f213448c208e0f0da5345c8635e2c635437d57ad66d186f07feb63b5bd0bbcddfae35b42e9e2873d65b4525e8be7f
+  data.tar.gz: 81f10062dc2f189ea2ca8e891139718048a24072ec7d9168391a9ce5eaee5baaf5f6d0359c36cc0cb323fd717821989bb5941a194a6b8c4c3f08159522aeb661

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+
+## 1.0.0 (2021-12-17)
+
+- Webhook can discard requests by multiple sender/events pairs
+
+## 0.3.0 (2021-10-04)
+
+- Add comment_id to Payload's context
+
+## 0.2.0 (2021-07-06)
+
+- Added support for `pull_request` type events
+
+## 0.1.0 (2021-07-01)
+
+- Added initial functionality and classes
+
+  - Issue::WebHook
+  - Issue::Payload
+  - Issue::Error
+
+## 0.0.1 (2021-06-29)
+
+- Gem created

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Juanjo Bazán
+
+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

@@ -1,2 +1,88 @@
-# issue
-Ruby gem to parse issue events coming from webhook payloads
+# Issue
+[![Gem Version](https://badge.fury.io/rb/issue.svg)](https://badge.fury.io/rb/issue)
+[![Tests](https://github.com/xuanxu/issue/actions/workflows/tests.yml/badge.svg)](https://github.com/xuanxu/issue/actions/workflows/tests.yml)
+
+Issue is a small library dedicated to parse requests coming from GitHub webhooks triggered by `issues`, `issue_comment` and `pull_request` events.
+
+## Getting started
+
+Depending on your project you may:
+
+Install the gem:
+```bash
+$ gem install issue
+```
+or add it to your Gemfile:
+```ruby
+gem 'issue'
+```
+
+Require the gem with:
+```ruby
+require 'issue'
+```
+
+## Usage
+
+The `Issue::Webhook` is used to declare and parse a GitHub webhook. At initialization it accepts a hash of configuration settings:
+
+- **secret_token**: The GitHub secret access token for authorization
+- **origin**: The repository to accept payloads from. If nil any origin will be accepted. If not nil any request from a different repository will be ignored
+- **discard_sender**: The GitHub handle of a user whose events will be ignored. Usually the organization bot. If nil no user will be ignored. To ignore only specific events use a Hash where keys are usernames and values are arrays of events to ignore for that username.
+- **accept_events**: An Array of GitHub event types to accept. If nil all events will be accepted.
+
+Once it is initialized a request can be parsed passing it to the **`parse_request`** method. After verifying the request signature and checking for the configurated conditions the `parse_request` method returns a [Payload, Error] pair, where the error is nil if nothing failed, and the payload is nil if an error ocurred.
+
+```ruby
+webhook = Issue::Webhook.new(secret_token: ENV["GH_SECRET"],
+                             origin: "myorg/reponame",
+                             discard_sender: "myorg_bot"
+                             accept_events: ["issues", "issue_comment"])
+
+payload, error = webhook.parse_request(request)
+
+if webhook.errored?
+  head error.status, msg: error.message
+else
+  # do_something_based_on_the(payload)
+  head 200
+end
+
+```
+
+### The Payload object
+
+The `Issue::Payload` object includes all the parsed information coming from the webhook request. It has the following instance methods:
+
+- **context**: This method returns a OpenStruct with the following structure:
+```ruby
+  action:             # the webhook action,
+  event:              # the GitHub event coming in the HTTP_X_GITHUB_EVENT request header
+  issue_id:           # the issue number
+  issue_title:        # issue title,
+  issue_body:         # body of the issue
+  issue_author:       # author of the issue
+  issue_labels:       # labels of the issue
+  repo:               # the full name of the origin repository
+  sender:             # the login of the user triggering the webhook action
+  event_action:       # a string: "event.action"
+  comment_id:         # id of the comment
+  comment_body:       # body of the comment
+  comment_created_at: # created_at value of the comment
+  comment_url:        # the html url for the comment
+  raw_payload:        # a hash with the complete parsed JSON request
+```
+- **accesor methods** for every key in the context
+- **opened?**: `true` if the action is `opened` or `reopened`
+- **closed?**: `true` if the action is `closed`
+- **commented?**: `true` if the action is `created`
+- **edited?**: `true` if the action is `edited`
+- **locked?**: `true` if the action is `locked`
+- **unlocked?**: `true` if the action is `unlocked`
+- **pinned?**: `true` if the action is `pinned` or `unpinned`
+- **assigned?**: `true` if the action is `assigned` or `unassigned`
+- **labeled?**: `true` if the action is `labeled` or `unlabeled`
+
+## License
+
+Released under the MIT license.

data/lib/issue/error.rb

@@ -0,0 +1,15 @@
+module Issue
+  class Error
+    attr :status
+    attr :message
+
+    # Initialize Issue::Error object with:
+    # status: html status code
+    # msg: message to send back in response
+    def initialize(status, msg)
+      @status = status
+      @message = msg
+    end
+
+  end
+end

data/lib/issue/payload.rb

@@ -0,0 +1,123 @@
+require "ostruct"
+require "json"
+
+module Issue
+  class Payload
+    attr_accessor :context
+
+    # Initialize Issue::Payload object with:
+    #
+    #   json_data: the parsed json sent from a GitHub webhook
+    #   event: the value of the HTTP_X_GITHUB_EVENT header
+    #
+    # Initializing a new Issue::Payload instance makes all this info
+    # from the json webhook available via accessor methods:
+    #
+    #   action
+    #   event
+    #   issue_id
+    #   issue_title
+    #   issue_body
+    #   issue_author
+    #   repo
+    #   sender
+    #   event_action
+    #   raw_payload
+    #
+    # And when the event is 'issue_comment' also:
+    #
+    #   comment_body
+    #   comment_created_at
+    #   comment_url
+    #
+    def initialize(json_data, event)
+      action = json_data.dig("action")
+      sender = json_data.dig("sender", "login")
+      repo = json_data.dig("repository", "full_name")
+
+      if event == "pull_request"
+        issue_id = json_data.dig("pull_request", "number")
+        issue_title = json_data.dig("pull_request", "title")
+        issue_body = json_data.dig("pull_request", "body")
+        issue_labels = json_data.dig("pull_request", "labels")
+        issue_author = json_data.dig("pull_request", "user", "login")
+      else
+        issue_id = json_data.dig("issue", "number")
+        issue_title = json_data.dig("issue", "title")
+        issue_body = json_data.dig("issue", "body")
+        issue_labels = json_data.dig("issue", "labels")
+        issue_author = json_data.dig("issue", "user", "login")
+      end
+
+      @context = OpenStruct.new(
+        action: action,
+        event: event,
+        issue_id: issue_id,
+        issue_title: issue_title,
+        issue_body: issue_body,
+        issue_author: issue_author,
+        issue_labels: issue_labels,
+        repo: repo,
+        sender: sender,
+        event_action: "#{event}.#{action}",
+        raw_payload: json_data
+      )
+
+      if event == "issue_comment"
+        @context[:comment_id] = json_data.dig("comment", "id")
+        @context[:comment_body] = json_data.dig("comment", "body")
+        @context[:comment_created_at] = json_data.dig("comment", "created_at")
+        @context[:comment_url] = json_data.dig("comment", "html_url")
+      end
+
+      @context.each_pair do |method_name, value|
+        define_singleton_method(method_name) {value}
+      end
+    end
+
+    # True if the payload is coming from an issue that has just been opened
+    def opened?
+      action == "opened" || action == "reopened"
+    end
+
+    # True if the payload is coming from an issue that has just been closed
+    def closed?
+      action == "closed"
+    end
+
+    # True if the payload is coming from a new comment
+    def commented?
+      action == "created"
+    end
+
+    # True if the payload is coming from an edition of a comment or issue
+    def edited?
+      action == "edited"
+    end
+
+    # True if the payload is coming from locking an issue
+    def locked?
+      action == "locked"
+    end
+
+    # True if the payload is coming from unlocking an issue
+    def unlocked?
+      action == "unlocked"
+    end
+
+    # True if the payload is coming from pinning or unpinning an issue
+    def pinned?
+      action == "pinned" || action == "unpinned"
+    end
+
+    # True if the payload is coming from un/assigning an issue
+    def assigned?
+      action == "assigned" || action == "unassigned"
+    end
+
+    # True if the payload is coming from un/labeling an issue
+    def labeled?
+      action == "labeled" || action == "unlabeled"
+    end
+  end
+end

data/lib/issue/version.rb

@@ -1,3 +1,3 @@
 module Issue
-  VERSION = "0.0.1"
+  VERSION = "1.0.0"
 end

data/lib/issue/webhook.rb

@@ -0,0 +1,102 @@
+require "ostruct"
+require "json"
+require "openssl"
+require "rack"
+
+module Issue
+  class Webhook
+    attr_accessor :secret_token
+    attr_accessor :request
+    attr_accessor :accept_origin
+    attr_accessor :discard_sender
+    attr_accessor :accept_events
+    attr_accessor :error
+    attr_accessor :payload
+
+    # Initialize the Issue::Webhook object
+    # This method should receive a Hash with the following settings:
+    #   secret_token: the GitHub secret token needed to verify the request signature.
+    #   accept_events: an Array of valid values for the HTTP_X_GITHUB_EVENT header. If empty any event will be processed.
+    #   origin: the respository where the webhook should be sent to be accepted. If empty any request will be processed.
+    #   discard_sender: an optional GitHub user handle to discard all events triggered by it.
+    def initialize(settings={})
+      @secret_token = settings[:secret_token]
+      @accept_origin = settings[:origin]
+      @accept_events = [settings[:accept_events]].flatten.compact.uniq.map(&:to_s)
+      @discard_sender = parse_discard_senders(settings[:discard_sender])
+    end
+
+    # This method will parse the passed request.
+    # If the request signature is incorrect or any of the conditions set
+    # via the initialization settings are not met an error will be created
+    # with the appropiate html status and message. Otherwise a Issue::Payload
+    # object will be created with the information contained in the request payload.
+    #
+    # This method returns a pair [payload, error] where only one of them will be nil
+    def parse_request(request)
+      @payload = nil
+      @error = nil
+      @request = request
+
+      if verify_signature
+        parse_payload
+      end
+
+      return [payload, error]
+    end
+
+    # This method returns True if parsing a request has generated an Issue::Error object
+    # That object will be available at the #error accessor method.
+    def errored?
+      !error.nil?
+    end
+
+    private
+
+    def parse_discard_senders(discard_sender_settings)
+      if discard_sender_settings.is_a?(String)
+        return { discard_sender_settings => [] }
+      elsif discard_sender_settings.is_a?(Hash)
+        return discard_sender_settings.transform_keys {|k| k.to_s }.transform_values {|v| [v].flatten}
+      else
+        return {}
+      end
+    end
+
+    def verify_signature
+      gh_signature = request.get_header "HTTP_X_HUB_SIGNATURE"
+      return error!(500, "Can't compute signature") if secret_token.nil? || secret_token.empty?
+      return error!(403, "Request missing signature") if gh_signature.nil? || gh_signature.empty?
+      request.body.rewind
+      payload_body = request.body.read
+      signature = "sha1=" + OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha1"), secret_token, payload_body)
+      return error!(403, "Signatures didn't match!") unless Rack::Utils.secure_compare(signature, gh_signature)
+      true
+    end
+
+    def parse_payload
+      begin
+        request.body.rewind
+        json_payload = JSON.parse(request.body.read)
+        event = request.get_header "HTTP_X_GITHUB_EVENT"
+        sender = json_payload.dig("sender", "login")
+        origin = json_payload.dig("repository", "full_name")
+      rescue JSON::ParserError
+        return error!(400, "Malformed request")
+      end
+
+      return error!(422, "No payload") if json_payload.nil? || json_payload.empty?
+      return error!(422, "No event") if event.nil?
+      return error!(200, "Event discarded") unless (accept_events.empty? || accept_events.include?(event))
+      return error!(200, "Event origin discarded") if (discard_sender[sender] == [] || discard_sender[sender].to_a.include?(event))
+      return error!(403, "Event origin not allowed") if (accept_origin && origin != accept_origin)
+
+      @payload = Issue::Payload.new(json_payload, event)
+    end
+
+    def error!(status, msg)
+      @error = Issue::Error.new(status, msg)
+      false
+    end
+  end
+end

data/lib/issue.rb

@@ -1,5 +1,6 @@
-require 'issue/version'
-
 module Issue
-
+  require_relative "issue/version"
+  require_relative "issue/payload"
+  require_relative "issue/webhook"
+  require_relative "issue/error"
 end

metadata

@@ -1,15 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: issue
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Juanjo Bazán
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-06-29 00:00:00.000000000 Z
+date: 2021-12-17 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: openssl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -38,23 +66,28 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.10'
-description: Receive, parse and manage GitHub webhook events for issues and issue's
+description: Receive, parse and manage GitHub webhook events for issues, PRs and issue's
   comments
 email:
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- LICENSE
 - README.md
 - lib/issue.rb
+- lib/issue/error.rb
+- lib/issue/payload.rb
 - lib/issue/version.rb
+- lib/issue/webhook.rb
 homepage: http://github.com/xuanxu/issue
 licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/xuanxu/issue/issues
-  changelog_uri: https://github.com/xuanxu/issue/blob/master/CHANGELOG.md
-  documentation_uri: https://www.rubydoc.info/gems/emoticon
+  changelog_uri: https://github.com/xuanxu/issue/blob/main/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/gems/issue
   homepage_uri: http://github.com/xuanxu/issue
   source_code_uri: http://github.com/xuanxu/issue
 post_install_message:
@@ -75,7 +108,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.15
+rubygems_version: 3.2.22
 signing_key:
 specification_version: 4
 summary: Manage webhook payload for issue events