bridgetown-deploy_hook 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 48fcc6269af2fb7964d63514ef469a0a6816ceab6392904e96047dbcb700b599
+  data.tar.gz: 82a3243dbcda7345a0b0243038685d8270cbc6af8c3e6457c6770b24c9a7b2d3
+SHA512:
+  metadata.gz: 5f2ebb6640d09564dd7573c7345cb440027dfd541aa8f4a5d432165d7b967e61444d8585c48d03999e154121df3a5d4fa2a026c31e966a0982f0b6a659b78e17
+  data.tar.gz: 6778c4a3638d745fe08145f9f6459a650f64128d98c3bb9cb92c6c0427e2d664ab50b8dfb4ccfd540d71523415fa282f69433792aaa4704684b36ae322f2a329

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0](https://github.com/michaelherold/bridgetown-deploy_hook/tree/v0.1.0) - 2023-03-11
+
+### Added
+
+- The ability to specify authorizers for any HTTP Authorization schemes, whether current or future, through the initializer. These can be anything responding to `#call` with a nilable string argument with a truthy value for success and a falsey one for failure.
+- The ability the set the route for the deploy hook.

data/CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing
+
+In the spirit of [free software](http://www.fsf.org/licensing/essays/free-sw.html), we encourage **everyone** to help improve this project. Here are some ways _you_ can contribute:
+
+* Use alpha, beta, and pre-release versions.
+* Report bugs.
+* Suggest new features.
+* Write or edit documentation.
+* Write specifications.
+* Write code (**no patch is too small**: fix typos, add comments, clean up inconsistent whitespace).
+* Refactor code.
+* Fix [issues](https://github.com/michaelherold/bridgetown-deploy_hook/issues).
+* Review patches.
+
+## Submitting an Issue
+
+We use the [GitHub issue tracker](https://github.com/michaelherold/bridgetown-deploy_hook/issues) to track bugs and features. Before submitting a bug report or feature request, check to make sure no one has already submitted it.
+
+When submitting a bug report, please include a `<details>` block that includes a stack trace and any details that may be necessary to reproduce the bug, including your gem version, Ruby version, and operating system. This looks like the following:
+
+```markdown
+<details>
+<summary>A description of the details block</summary>
+
+All of the content that you want in here, perhaps with code fences. Note that
+if you only have a code fence in here, you _must_ separate it from the <summary>
+tag and the closing </details> or it won't render correctly.
+
+Notice the empty line here ↓
+
+</details>
+```
+
+Ideally, a bug report should include a pull request with failing specs.
+
+## Submitting a Pull Request
+
+1. Fork the repository.
+2. Create a topic branch.
+3. Add specs for your unimplemented feature or bug fix.
+4. Run `bundle exec rake test`. If your specs pass, return to step 3.
+5. Implement your feature or bug fix.
+6. Run `bundle exec rake`. If your specs or any of the linters fail, return to step 5.
+7. Open `coverage/index.html`. If your changes are not fully covered by your tests, return to step 3.
+8. Add documentation for your feature or bug fix.
+9. Commit and push your changes.
+10. Submit a pull request.
+
+## Tools to Help You Succeed
+
+After checking out the repository, run `bin/setup` to install dependencies. Then, run `bundle exec rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+Before committing code, run `bundle exec rake` to check that the code conforms to the style guidelines of the project, that all of the tests are green (if you're writing a feature; if you're only submitting a failing test, then it does not have to pass!), and that you sufficiently documented the changes.

data/LICENSE.md

@@ -0,0 +1,21 @@
+# The MIT License (MIT)
+
+Copyright © 2023 Michael Herold
+
+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,98 @@
+# Bridgetown deploy hook plugin
+
+A [Bridgetown](https://www.bridgetownrb.com) plugin for triggering behavior via a webhook.
+
+## Installation
+
+Run this command to add this plugin to your site's Gemfile:
+
+    bundle add bridgetown-deploy_hook
+
+Or you can use [an automation script](https://www.bridgetownrb.com/docs/automations) instead for guided setup:
+
+    bin/bt apply https://github.com/michaelherold/bridgetown-deploy_hook
+
+## Usage
+
+To use a post-deploy hook, you must run Bridgetown with the Roda app; a static website will not work. First, add the Roda plugin to your app and call the helper for enabling the route:
+
+```ruby
+# server/roda_app.rb
+class RodaApp < Bridgetown::Rack::Roda
+  plugin :bridgetown_ssr
+  plugin :bridgetown_deploy_hook
+  
+  route do |r|
+    r.bridgetown_deploy_hook
+  end
+end
+```
+
+Note that you must enable the plugin _after_ the `:bridgetown_ssr` plugin because the latter is what sets up your Bridgetown site for use by the Roda app.
+
+Next, configure your route and authorization methods using the initializer. For example, if you want `/my-deploy-hook` to be the route for your hook and use a static [Bearer token](https://datatracker.ietf.org/doc/html/rfc6750) from your environment variables as an authorization mechanism:
+
+```ruby
+# config/initializers.rb
+
+Bridgetown.configure do
+  init(
+    "bridgetown-deploy_hook",
+    authorization: {
+      bearer: ->(token) { token == ENV["BEARER_TOKEN"] }
+    }
+    route: "my-deploy-hook"
+  )
+end
+```
+
+Lastly, register the action that you want to run with the deploy hook:
+
+```ruby
+# config/initializers.rb
+# ... or any other auto-loaded file in your app
+Bridgetown::Hooks.register_one :site, :post_deploy do |site|
+  # Your code here
+end
+```
+
+`site` is your `Bridgetown::Site` instance so you have access to all of your configuration and resources that you have configured.
+
+### Authorization
+
+You may register anything that responds to `#call`, takes a string argument of the directives for your authorization type, and responds with a truthy value when authorization succeeds.
+
+Each [authorization scheme](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#authentication_schemes) may have a single handler registered to it. Register them with either the symbol or string cooresponding to the lowercase version of the scheme. For example, if you want to register both a [Basic](https://datatracker.ietf.org/doc/html/rfc7617) handler and a [Bearer](https://datatracker.ietf.org/doc/html/rfc6750) handler, that would look like the following:
+
+```ruby
+# config/initializers.rb
+
+Bridgetown.configure do
+  init(
+    "bridgetown-deploy_hook",
+    authorization: {
+      basic: my_basic_handler,
+      bearer: my_bearer_handler,
+    }
+    route: "my-deploy-hook"
+  )
+end
+```
+
+The **handlers receive the raw value from the header**, not a destructured version. So the Basic handler receives the Base64-encoded `user:password` pair, not the user and the password, so you must handle the parsing of the value appropriately for the authorization scheme.
+
+### Plugin authors
+
+Plugins may also interact with the deploy hook by registering their own [non-reloadable](https://www.bridgetownrb.com/docs/plugins/hooks#reloadable-vs-non-reloadable-hooks) hook handlers.
+
+As an example:
+
+```ruby
+Bridgetown::Hooks.register_one :site, :post_deploy, reloadable: false do |site|
+  MyPlugin.do_the_work(site)
+end
+```
+
+## Contributing
+
+So you're interested in contributing to Bridgetown deploy hook? Check out our [contributing guidelines](CONTRIBUTING.md) for more information on how to do that.

data/bridgetown-deploy_hook.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "lib/bridgetown/deploy_hook/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "bridgetown-deploy_hook"
+  spec.version = Bridgetown::DeployHook::VERSION
+  spec.authors = ["Michael Herold"]
+  spec.email = ["opensource@michaeljherold.com"]
+  spec.summary = "Add a Bridgetown hook triggered by HTTP for running post-deploy actions"
+  spec.description = spec.summary
+  spec.homepage = "https://github.com/michaelherold/bridgetown-deploy_hook"
+  spec.license = "MIT"
+
+  spec.files = %w[CHANGELOG.md CONTRIBUTING.md LICENSE.md README.md]
+  spec.files += %w[bridgetown-deploy_hook.gemspec]
+  spec.files += Dir["lib/**/*.rb"]
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.add_dependency "bridgetown", ">= 1.2", "< 2.0"
+  spec.add_dependency "zeitwerk"
+
+  spec.add_development_dependency "bundler", ">= 2"
+
+  spec.metadata = {
+    "bug_tracker_uri" => "https://github.com/michaelherold/bridgetown-deploy_hook/issues",
+    "changelog_uri" => "https://github.com/michaelherold/bridgetown-deploy_hook/blob/main/CHANGELOG.md",
+    "documentation_uri" => "https://rubydoc.info/gems/bridgetown-deploy_hook/#{Bridgetown::DeployHook::VERSION}",
+    "homepage_uri" => "https://github.com/michaelherold/bridgetown-deploy_hook",
+    "rubygems_mfa_required" => "true",
+    "source_code_uri" => "https://github.com/michaelherold/bridgetown-deploy_hook"
+  }
+end

data/lib/bridgetown/deploy_hook/authorization.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Bridgetown
+  module DeployHook
+    # Handles authorizing a request via its [Authorization header][1]
+    #
+    # You can configure the authorization strategies via the
+    # bridgetown-deploy_hook initializer. For example, if you want to allow a
+    # [Bearer token][2], give the configuration a callable at the `:bearer`
+    # value in the authorization parameter.
+    #
+    # @example Allowing a specific Bearer token
+    #
+    #   Bridgetown.configure do
+    #     init(
+    #       "bridgetown-deploy_hook",
+    #       authorization: {
+    #         bearer: ->(token) { token == "myvaluemaybefromtheenvironment" }
+    #       }
+    #     )
+    #   end
+    #
+    # The webhook handler parses the Authorization header and dispatches the
+    # authorization request to the appropriate scheme registered in the
+    # configuration. For example, if you want to allow [HTTP Basic
+    # authorization][3], the scheme is `Basic` so register the `:basic` or
+    # `"basic"` key in the site configuration.
+    #
+    # The authorization parameters are passed directly without any parsing or
+    # conversion so your interpreter will need to be able to convert the raw
+    # string appropriately. Missing values will end up with a `nil` so ensure
+    # you handle the `nil` case as well.
+    #
+    # Handlers can be anything that responds to a `#call` of a String or `nil`
+    # with a Boolean (or any truthy/falsey combination if that floats your
+    # boat).
+    #
+    # [1]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization
+    # [2]: https://datatracker.ietf.org/doc/html/rfc6750
+    # [3]: https://datatracker.ietf.org/doc/html/rfc7617
+    class Authorization
+      # The default authorizer that rejects everything
+      #
+      # @private
+      #
+      # @return [#call<String, nil>: Boolean] the authorizer
+      REJECT_ALL = ->(*) { false }.freeze
+
+      # Initializes a new {Authorization}
+      #
+      # @since 0.1.0
+      # @api public
+      #
+      # @example Using the authorizers from the current Bridgetown site
+      #
+      #   Bridgetown::DeployHook::Authorization.new(
+      #     "Basic YmlsYm86dGVzdA==",
+      #     config: Bridgetown::Current.site.config.deploy_hook
+      #   )
+      #
+      # @param header [String, nil] the value from the Authorization header
+      # @param config [HashWithDotAccess::Hash] the deploy hook configuration
+      #   for a `Bridgetown::Site`
+      # @return [void]
+      def initialize(header, config:)
+        scheme, @parameters = header&.split(" ", 2)
+        @authorizer = config.authorization.fetch(scheme&.downcase, REJECT_ALL)
+      end
+
+      # Authorizes the request based on its Authorization header
+      #
+      # @since 0.1.0
+      # @api public
+      #
+      # @example Authorizing every Bearer token (don't do this!)
+      #
+      #   auth = Bridgetown::DeployHook::Authorization.new(
+      #     "Bearer 123",
+      #     config: HashWithDotAccess::Hash.new(
+      #       authorization: {bearer: ->(_) { true }}
+      #     )
+      #   )
+      #   auth.call #=> true
+      #
+      # @return [Boolean] true when authorized, false otherwise
+      def call
+        authorizer.call(parameters)
+      end
+
+      private
+
+      # The authorizer responsible for checking the header value
+      #
+      # This can be anything that responds to a `#call` of a String or `nil`
+      # with a Boolean.
+      #
+      # @api private
+      # @private
+      #
+      # @return [#call<String, nil>: Boolean]
+      attr_reader :authorizer
+
+      # The parameters extracted from the Authorization header
+      #
+      # @api private
+      # @private
+      #
+      # @return [String, nil]
+      attr_reader :parameters
+    end
+  end
+end

data/lib/bridgetown/deploy_hook/initializer.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# @param config [HashWithDotAccess::Hash] the configuration for the Bridgetown site
+# @param authorization [Hash<(Symbol, String, nil), #call<String, nil>: Boolean>] a
+#   Hash mapping Authorization schemes to authenticators, callables that map
+#   string-encoded parameters to Boolean values to indicate whether the attempt
+#   was a success or failure
+# @param route [String] the route for the deploy hook within the Roda application
+Bridgetown.initializer "bridgetown-deploy_hook" do |config, authorization: {}, route: "_bridgetown/deploy"|
+  options = {authorization: authorization, route: route}
+
+  # :nocov: Because it's not possible to show coverage for both branches
+  if config.deploy_hook
+    config.deploy_hook Bridgetown::Utils.deep_merge_hashes(options, config.deploy_hook)
+  else
+    config.deploy_hook(options)
+  end
+  # :nocov:
+end

data/lib/bridgetown/deploy_hook/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Bridgetown
+  module DeployHook
+    # The current version of the gem
+    #
+    # @private
+    VERSION = "0.1.0"
+  end
+end

data/lib/bridgetown-deploy_hook.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "bridgetown/deploy_hook/version"
+
+# A progressive site generator and fullstack framework
+#
+# @see https://www.bridgetownrb.com/
+module Bridgetown
+  # A Bridgetown plugin that adds support for post-deploy webhooks
+  #
+  # Post-deploy actions receive the Bridgetown site as a block parameter so can
+  # operate on the site as a whole if they wish. This could be for sending
+  # Webmentions or other linkbacks, notifying your team of a deployment for a
+  # client site, or anything else you might find yourself needing to do.
+  #
+  # @example Adding a post-deploy hook to send a Slack notification
+  #
+  #   Bridgetown::Hooks.register_one :site, :post_deploy do |site|
+  #     SendSlackNotification.call(site)
+  #   end
+  module DeployHook
+    # The Zeitwerk loader responsible for auto-loading constants
+    #
+    # @private
+    Loader = Zeitwerk::Loader.for_gem(warn_on_extra_files: false).tap do |loader|
+      loader.ignore(__FILE__)
+      loader.ignore(File.join(__dir__, "bridgetown", "deploy_hook", "initializer"))
+      loader.ignore(File.join(__dir__, "roda", "plugins", "deploy_hook"))
+      loader.setup
+    end
+  end
+end
+
+require_relative "bridgetown/deploy_hook/initializer"

data/lib/roda/plugins/bridgetown_deploy_hook.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+# A routing tree for building Rack applications
+#
+# @see https://roda.jeremyevans.net/
+class Roda
+  # The namespace Roda uses for loading plugins by convention
+  module RodaPlugins
+    # A plugin that integrates a post-deploy webhook into a Bridgetown Roda app
+    #
+    # This plugin requires the Bridgetown SSR plugin to be enabled before it.
+    #
+    # It creates a route via the configuration set in the initializer that
+    # authorizes requests via {Bridgetown::DeployHook::Authorization} and runs
+    # the post deploy hook when authorized.
+    #
+    # See {Bridgetown::DeployHook} for an example of adding a post-deploy hook.
+    #
+    # See {Bridgetown::DeployHook::Authorization} for more information about
+    # authorization strategies.
+    module BridgetownDeployHook
+      # The string representing an empty response body
+      #
+      # @api private
+      # @private
+      EMPTY_BODY = ""
+
+      # The Roda hook for configuring the plugin
+      #
+      # @since 0.1.0
+      # @api public
+      #
+      # @example Adding the plugin to your Bridgetown Roda app
+      #
+      #    class RodaApp < Bridgetown::Rack::Roda
+      #      plugin :bridgetown_ssr
+      #      plugin :bridgetown_deploy_hook
+      #    end
+      #
+      # @param app [::Roda] the Roda application to configure
+      # @return [void]
+      def self.configure(app)
+        return unless app.opts[:bridgetown_site].nil?
+
+        # :nocov: Because it's difficult to set up multiple contexts
+        raise(
+          "Roda app failure: the bridgetown_ssr plugin must be registered before " \
+          "bridgetown_deploy_hook"
+        )
+        # :nocov:
+      end
+
+      # Methods included in to the Roda request
+      #
+      # @see http://roda.jeremyevans.net/rdoc/classes/Roda/RodaPlugins/Base/RequestMethods.html
+      module RequestMethods
+        # Builds the deploy hook route within the Roda application
+        #
+        # @since 0.1.0
+        # @api public
+        #
+        # @example Enabling the deploy hook route
+        #
+        #   class RodaApp < Bridgetown::Rack::Roda
+        #     plugin :bridgetown_ssr
+        #     plugin :bridgetown_deploy_hook
+        #
+        #     route do |r|
+        #       r.bridgetown_deploy_hook
+        #     end
+        #   end
+        #
+        # @return [void]
+        def bridgetown_deploy_hook
+          site = roda_class.opts[:bridgetown_site]
+          config = site.config.deploy_hook
+
+          on(config.route) do
+            is do
+              authorization = Bridgetown::DeployHook::Authorization.new(
+                env["HTTP_AUTHORIZATION"],
+                config: config
+              )
+
+              response["Content-Type"] = "application/json"
+
+              if (authorized = authorization.call)
+                response.status = 200
+                response.write('{"status":"success"}')
+              else
+                response["WWW-Authenticate"] = config.authorization.keys
+                response.status = 401
+
+                response.write('{"status":"error","error":"unauthorized"}')
+              end
+
+              get do
+                Bridgetown::Hooks.trigger(:site, :post_deploy, site) if authorized
+
+                halt response.finish
+              end
+
+              head do
+                response.finish # to properly set the Content-Length header
+                halt response.finish_with_body(EMPTY_BODY)
+              end
+            end
+          end
+        end
+      end
+    end
+
+    register_plugin :bridgetown_deploy_hook, BridgetownDeployHook
+  end
+end

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: bridgetown-deploy_hook
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Michael Herold
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-03-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bridgetown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  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: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2'
+description: Add a Bridgetown hook triggered by HTTP for running post-deploy actions
+email:
+- opensource@michaeljherold.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CONTRIBUTING.md
+- LICENSE.md
+- README.md
+- bridgetown-deploy_hook.gemspec
+- lib/bridgetown-deploy_hook.rb
+- lib/bridgetown/deploy_hook/authorization.rb
+- lib/bridgetown/deploy_hook/initializer.rb
+- lib/bridgetown/deploy_hook/version.rb
+- lib/roda/plugins/bridgetown_deploy_hook.rb
+homepage: https://github.com/michaelherold/bridgetown-deploy_hook
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/michaelherold/bridgetown-deploy_hook/issues
+  changelog_uri: https://github.com/michaelherold/bridgetown-deploy_hook/blob/main/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/bridgetown-deploy_hook/0.1.0
+  homepage_uri: https://github.com/michaelherold/bridgetown-deploy_hook
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/michaelherold/bridgetown-deploy_hook
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.32
+signing_key:
+specification_version: 4
+summary: Add a Bridgetown hook triggered by HTTP for running post-deploy actions
+test_files: []