waffo-pancake 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5283cad4a209984c83a1416a5b8a56ba039935e1d7c4ed3879349f5eeb6e5f7
-  data.tar.gz: 76a97790c5458a0ce01f9edc5c88f54bada6b04d29abd2904f768b35b06d4213
+  metadata.gz: b498f6ef1ac1fbdec66122b1a9d4758ebd6ea917840563c8f296c9e020c03bdd
+  data.tar.gz: c34ede893f8f1a84c2d6f7e71968dddfed09ce1a20e43140156805cf2bf93e39
 SHA512:
-  metadata.gz: 9f96eae8643cd2f8bc76c8ad36c4b48f991b0df654a1c696bf5cb53c5bbe0a48f9fa291809e3a3370aed504d3b7aeeda34b959ad91312cc62f1d21c0c0c95569
-  data.tar.gz: 21cc4f957a948cce53f880578094f8fece93ce4cc58f73500d1d82b0f8f3ef62d41f3ac012d4df92a42e017b99e53c85a269475445277b397938376714bebc4c
+  metadata.gz: bee472c21659562c0a68275d615eb5af3f21d95ec1937f2aed7fab7a5570b1f968e6b27f3ff4bbd7fa82598eef3e30407b35afbf8503759cca44490aa9e3bb85
+  data.tar.gz: f96b92d6942e7a94e298153a02c1f9a5b480afb1c399ba420da5044964bbe7f946ca6d02f09c54086d256f2881485ff250c166536223d7493122fc01b8577926

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.2.1
+
+- `Client#subscription_order` also returns the order's current product as `productId`, read
+  from `subscriptionProduct { id }`, so a plan change to another product can be detected.
+
+## 0.2.0
+
+- `Waffo::Pancake.configure` / `.configuration`: process-wide settings that start from the
+  `WAFFO_*` environment variables, a shared `Waffo::Pancake.client`, and
+  `Waffo::Pancake.verify_webhook` using the configured environment, key and tolerances.
+  `Client.new` arguments now default to the configuration (still the environment variables when
+  nothing is configured).
+- Rails integration, loaded only inside a Rails app:
+  - A Railtie that reads `credentials.waffo` and `config.waffo_pancake`, logs to `Rails.logger`
+    and filters `private_key` from logs.
+  - `Waffo::Pancake::WebhookController`, a controller concern that verifies the signature
+    before the action, keeps the payload out of params and the request log, and acknowledges
+    deliveries for another environment or store without running the action.
+  - `bin/rails generate waffo_pancake:install`: initializer, route, webhook controller, and
+    (unless `--skip-events-table`) a `waffo_webhook_events` table, model and job.
+- Instrumentation: `request.waffo_pancake` for each API request and
+  `verify_webhook.waffo_pancake` for each webhook check, through ActiveSupport::Notifications
+  when it is loaded or any `instrumenter` you configure.
+- `Waffo::Pancake::TestHelpers`: signed webhook headers for a throwaway key, event builders, and
+  `FakeClient` to stand in for the API.
+
 ## 0.1.0
 
 - `Waffo::Pancake::Client`: signed merchant API requests (RSA-SHA256, `X-Merchant-Id` /

data/README.md

@@ -14,6 +14,22 @@ gem "waffo-pancake"
 
 ## Configure
 
+Settings come from `Waffo::Pancake.configure`, which starts from the `WAFFO_*` environment
+variables (`WAFFO_MERCHANT_ID`, `WAFFO_PRIVATE_KEY`, `WAFFO_STORE_ID`, `WAFFO_ENVIRONMENT`):
+
+```ruby
+Waffo::Pancake.configure do |config|
+  config.merchant_id = "MER_..."
+  config.private_key = File.read("waffo.pem")
+  config.store_id = "STO_..."
+  config.environment = "prod"   # which webhook key to trust; nil tries prod, then test
+end
+
+Waffo::Pancake.client.cancel_subscription("ORD_...")   # a client built from the configuration
+```
+
+Or build a client yourself:
+
 Create an API key in the Dashboard (**API & Development**). A key is bound to test or prod
 when it is created, so the key decides the environment.
 
@@ -115,6 +131,94 @@ both), or pass `public_key:`. Timestamps may be up to 45 minutes old and 1 minut
 
 `Waffo::Pancake::Webhook::EVENT_TYPES` lists the event types.
 
+## Rails
+
+Inside a Rails app the gem configures itself. Settings are read in this order, the last one
+winning: `WAFFO_*` environment variables, `credentials.waffo`, `config.waffo_pancake`, then
+`Waffo::Pancake.configure` in an initializer. The logger is `Rails.logger`, and `private_key`
+is added to `filter_parameters`.
+
+```yaml
+# bin/rails credentials:edit
+waffo:
+  merchant_id: MER_...
+  private_key: "-----BEGIN PRIVATE KEY-----\n..."
+  store_id: STO_...
+  environment: prod
+```
+
+```sh
+bin/rails generate waffo_pancake:install          # add --skip-events-table to leave out the table
+bin/rails db:migrate
+```
+
+The generator adds `config/initializers/waffo_pancake.rb`, a `POST /webhooks/waffo` route, and
+`WaffoWebhooksController`. Unless `--skip-events-table` is given it also adds a
+`waffo_webhook_events` table (one row per delivery id, so a retry is not handled twice), its
+model and a `WaffoWebhookJob` to fill in.
+
+The controller uses the `Waffo::Pancake::WebhookController` concern, which you can also include
+in your own controller:
+
+```ruby
+class WaffoWebhooksController < ActionController::Base
+  include Waffo::Pancake::WebhookController
+
+  def create
+    HandleWaffoEventJob.perform_later(waffo_event)   # verified, parsed delivery
+    head :ok
+  end
+end
+```
+
+Before the action the concern:
+
+- verifies `X-Waffo-Signature` with the configured key, and answers 401 if it fails;
+- answers 413 for a body over 256 KB;
+- answers 200 without running the action when the delivery is for another `environment` or `store_id` (when those are configured), since an error status only makes Waffo retry it;
+- keeps the payload out of `params` and the request log.
+
+### Instrumentation
+
+With ActiveSupport loaded (or any object answering `instrument(name, payload) { }` set as
+`config.instrumenter`), the gem reports:
+
+| Event | Payload |
+|---|---|
+| `request.waffo_pancake` | `method`, `path`, `status` (nil when there was no answer), `exception` when raised |
+| `verify_webhook.waffo_pancake` | `environment`, `event_id`, `event_type`, `mode`, `exception` when refused |
+
+```ruby
+ActiveSupport::Notifications.subscribe("request.waffo_pancake") do |event|
+  Rails.logger.info("Waffo #{event.payload[:path]} #{event.payload[:status]} #{event.duration.round}ms")
+end
+```
+
+### Testing
+
+```ruby
+# spec/rails_helper.rb (or test/test_helper.rb with ActiveSupport::TestCase)
+require "waffo/pancake/test_helpers"
+RSpec.configure { |config| config.include Waffo::Pancake::TestHelpers }
+
+it "accepts a signed delivery" do
+  body = waffo_webhook_event("subscription.activated", data: { "orderId" => "ORD_1" }).to_json
+  with_waffo_webhook_key { post "/webhooks/waffo", params: body, headers: waffo_webhook_headers(body) }
+  expect(response).to have_http_status(:ok)
+end
+
+it "cancels at Waffo" do
+  with_fake_waffo_client(Waffo::Pancake::TestHelpers::FakeClient.new("ORD_1" => { "status" => "active" })) do |waffo|
+    post "/billing/cancel"
+    expect(waffo.calls).to include([:cancel_subscription, "ORD_1"])
+  end
+end
+```
+
+`FakeClient` answers `subscription_order` from the orders it was given, moves an order to
+`canceling` / `active` on cancel / reactivate, records every call in `calls`, and raises
+`fail_with` when set.
+
 ## Errors
 
 | Class | When |
@@ -142,10 +246,11 @@ Test cards: `4576 7500 0000 0110` succeeds and `4576 7500 0000 0220` is declined
 
 ```sh
 bundle install
-bundle exec rake test
+bundle exec rake test        # test:core (no Rails loaded) and test:rails
 ```
 
-Releases are published to RubyGems by the `Release` workflow when a `v*` tag is pushed. It uses
+Releases are published to RubyGems by the `Release` workflow when a `v*` tag is pushed (see
+[RELEASING.md](RELEASING.md)). It uses
 [trusted publishing](https://guides.rubygems.org/trusted-publishing/), so no API key is stored.
 
 ## License

data/lib/generators/waffo_pancake/install/install_generator.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/migration"
+
+module WaffoPancake
+  module Generators
+    # bin/rails generate waffo_pancake:install [--skip-events-table]
+    class InstallGenerator < ::Rails::Generators::Base
+      include ::Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Adds a Waffo Pancake initializer and a verified webhook endpoint, with a table that " \
+           "records each delivery once and a job that handles it."
+
+      class_option :events_table, type: :boolean, default: true,
+                                  desc: "Record deliveries in waffo_webhook_events and handle them in a job"
+
+      def self.next_migration_number(dirname)
+        require "rails/generators/active_record"
+        ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/waffo_pancake.rb"
+      end
+
+      def create_controller
+        template "webhooks_controller.rb", "app/controllers/waffo_webhooks_controller.rb"
+      end
+
+      def add_route
+        route 'post "webhooks/waffo", to: "waffo_webhooks#create", as: :waffo_webhook'
+      end
+
+      def create_events_table
+        return unless events_table?
+
+        migration_template "create_waffo_webhook_events.rb", "db/migrate/create_waffo_webhook_events.rb"
+        template "webhook_event.rb", "app/models/waffo_webhook_event.rb"
+        template "webhook_job.rb", "app/jobs/waffo_webhook_job.rb"
+      end
+
+      def show_next_steps
+        say <<~TEXT
+
+          Waffo Pancake is installed. Next:
+            1. Add credentials (bin/rails credentials:edit) or WAFFO_* environment variables:
+                 waffo:
+                   merchant_id: MER_...
+                   private_key: "-----BEGIN PRIVATE KEY-----\\n..."
+                   store_id: STO_...
+                   environment: test
+            #{events_table? ? "2. bin/rails db:migrate" : "2. Deduplicate deliveries on waffo_event[\"id\"] in WaffoWebhooksController"}
+            3. In the Waffo Dashboard, add a webhook pointing at https://<your host>/webhooks/waffo
+               and subscribe to the events you handle.
+        TEXT
+      end
+
+      private
+        def events_table? = options[:events_table]
+
+        def migration_version
+          "[#{::ActiveRecord::Migration.current_version}]" if defined?(::ActiveRecord::Migration)
+        end
+    end
+  end
+end

data/lib/generators/waffo_pancake/install/templates/create_waffo_webhook_events.rb.tt

@@ -0,0 +1,16 @@
+class CreateWaffoWebhookEvents < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :waffo_webhook_events do |t|
+      t.string :delivery_id, null: false
+      t.string :event_type, null: false
+      t.string :mode, null: false
+      t.string :order_id
+      t.json :payload, null: false
+      t.datetime :processed_at
+      t.timestamps
+    end
+
+    add_index :waffo_webhook_events, :delivery_id, unique: true
+    add_index :waffo_webhook_events, :order_id
+  end
+end

data/lib/generators/waffo_pancake/install/templates/initializer.rb.tt

@@ -0,0 +1,17 @@
+# Waffo Pancake (the waffo-pancake gem). Settings are read in this order, the last one winning:
+# WAFFO_* environment variables, credentials.waffo, config.waffo_pancake, then this block.
+#
+#   # bin/rails credentials:edit
+#   waffo:
+#     merchant_id: MER_...
+#     private_key: "-----BEGIN PRIVATE KEY-----\n..."   # PEM, or bare base64
+#     store_id: STO_...
+#     environment: test                                 # or prod
+#
+# Waffo::Pancake.client is a client built from these settings; webhook deliveries are verified
+# by Waffo::Pancake::WebhookController. Requests are reported as `request.waffo_pancake` and
+# webhook checks as `verify_webhook.waffo_pancake` ActiveSupport::Notifications events.
+Waffo::Pancake.configure do |config|
+  # config.environment = Rails.env.production? ? "prod" : "test"
+  # config.timeout = 15
+end

data/lib/generators/waffo_pancake/install/templates/webhook_event.rb.tt

@@ -0,0 +1,17 @@
+# One verified Waffo Pancake delivery. The unique delivery_id makes a redelivery a no-op.
+class WaffoWebhookEvent < ApplicationRecord
+  # Returns [event, created?]; two deliveries racing on the unique index share the one row.
+  def self.record(event)
+    attributes = {
+      event_type: event["eventType"].to_s,
+      mode: event["mode"].to_s,
+      order_id: event.dig("data", "orderId"),
+      payload: event
+    }
+    [ create!(delivery_id: event["id"].to_s, **attributes), true ]
+  rescue ActiveRecord::RecordNotUnique
+    [ find_by!(delivery_id: event["id"].to_s), false ]
+  end
+
+  def data = payload.fetch("data", {})
+end

data/lib/generators/waffo_pancake/install/templates/webhook_job.rb.tt

@@ -0,0 +1,25 @@
+# Handles one Waffo Pancake delivery (WaffoWebhooksController records it first). Event types:
+# https://docs.waffo.ai — Waffo::Pancake::Webhook::EVENT_TYPES lists them.
+class WaffoWebhookJob < ApplicationJob
+  retry_on Waffo::Pancake::Unavailable, wait: :polynomially_longer, attempts: 8
+
+  def perform(event)
+    return if event.processed_at
+
+    case event.event_type
+    when "subscription.activated", "subscription.renewed", "subscription.recovered", "subscription.uncanceled"
+      # Grant access until event.data["currentPeriodEnd"]. To read the order as Waffo has it
+      # now, regardless of delivery order: Waffo::Pancake.client.subscription_order(event.order_id)
+    when "subscription.canceling"
+      # Access continues until event.data["currentPeriodEnd"]; no renewal follows.
+    when "subscription.canceled"
+      # Revoke access.
+    when "subscription.past_due"
+      # The renewal failed; the payment channel retries once, usually the next day.
+    when "refund.succeeded"
+      # Compare event.data["refundedAmount"] with event.data["originalChargedAmount"].
+    end
+
+    event.update!(processed_at: Time.current)
+  end
+end

data/lib/generators/waffo_pancake/install/templates/webhooks_controller.rb.tt

@@ -0,0 +1,16 @@
+# Receives Waffo Pancake webhooks. The included concern has already verified the signature,
+# the environment and the store before `create` runs; `waffo_event` is the parsed delivery.
+class WaffoWebhooksController < ActionController::Base
+  include Waffo::Pancake::WebhookController
+
+  def create
+<% if events_table? -%>
+    event, created = WaffoWebhookEvent.record(waffo_event)
+    WaffoWebhookJob.perform_later(event) if created
+<% else -%>
+    # A retry redelivers the same waffo_event["id"]; handle each id once.
+    Rails.logger.info("Waffo #{waffo_event["eventType"]} #{waffo_event["id"]}")
+<% end -%>
+    head :ok
+  end
+end

data/lib/waffo/pancake/client.rb

@@ -30,6 +30,7 @@ module Waffo
           subscriptionOrder(id: $id) {
             id storeId status testMode buyerEmail merchantProvidedBuyerIdentity orderMerchantExternalId
             billingPeriod currentPeriodStart currentPeriodEnd canceledAt
+            subscriptionProduct { id }
           }
         }
       GRAPHQL
@@ -44,11 +45,14 @@ module Waffo
         Base64.strict_encode64(private_key.sign(OpenSSL::Digest::SHA256.new, canonical))
       end
 
-      # `transport` replaces the HTTP call: it takes the URI, the headers and the JSON body
-      # and answers `[status, body]` (status nil when there was no answer). `logger` gets one
-      # info line per request; neither the body nor the key is ever logged.
-      def initialize(merchant_id: ENV["WAFFO_MERCHANT_ID"], private_key: ENV["WAFFO_PRIVATE_KEY"],
-                     base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT, logger: nil, transport: nil)
+      # Every argument defaults to Waffo::Pancake.configuration (itself defaulting to the
+      # WAFFO_* environment variables). `transport` replaces the HTTP call: it takes the URI,
+      # the headers and the JSON body and answers `[status, body]` (status nil when there was
+      # no answer). `logger` gets one info line per request and `instrumenter` one
+      # `request.waffo_pancake` event; neither ever sees the body or the key.
+      def initialize(config: Pancake.configuration, merchant_id: config.merchant_id, private_key: config.private_key,
+                     base_url: config.base_url, timeout: config.timeout, logger: config.logger,
+                     instrumenter: config.instrumenter, transport: nil)
         raise ConfigurationError, "Missing merchant_id (WAFFO_MERCHANT_ID)" if blank?(merchant_id)
         raise ConfigurationError, "Missing private_key (WAFFO_PRIVATE_KEY)" if blank?(private_key)
 
@@ -57,6 +61,7 @@ module Waffo
         @base_url = base_url.to_s.chomp("/")
         @timeout = timeout
         @logger = logger
+        @instrumenter = instrumenter
         @transport = transport || method(:http_post)
       end
 
@@ -105,9 +110,11 @@ module Waffo
         action("/v1/actions/onetime-order/cancel-order", { order_id: order_id })
       end
 
-      # Nil when Waffo knows no such order.
+      # Nil when Waffo knows no such order. `productId` is the order's current product, so a plan
+      # change to another product can be told apart.
       def subscription_order(order_id)
-        graphql(SUBSCRIPTION_ORDER_QUERY, id: order_id)&.dig("subscriptionOrder")
+        order = graphql(SUBSCRIPTION_ORDER_QUERY, id: order_id)&.dig("subscriptionOrder")
+        order && order.merge("productId" => order.dig("subscriptionProduct", "id"))
       end
 
       # --- Products ----------------------------------------------------------------------
@@ -174,7 +181,9 @@ module Waffo
           }
 
           started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-          status, body = call_transport(URI("#{@base_url}#{path}"), headers, json)
+          status, body = instrument("request.waffo_pancake", method: "POST", path: path) do |payload|
+            call_transport(URI("#{@base_url}#{path}"), headers, json).tap { |answer| payload[:status] = answer.first }
+          end
           elapsed = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started).round(2)
           @logger&.info("[Waffo] POST #{path} status=#{status.inspect} in #{elapsed}s")
 
@@ -186,6 +195,12 @@ module Waffo
           [status, envelope]
         end
 
+        def instrument(name, payload, &block)
+          return yield(payload) unless @instrumenter
+
+          @instrumenter.instrument(name, payload, &block)
+        end
+
         def call_transport(uri, headers, json)
           @transport.call(uri, headers, json)
         rescue *NETWORK_ERRORS => e

data/lib/waffo/pancake/configuration.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Waffo
+  module Pancake
+    # Process-wide settings, read by `Waffo::Pancake.client`, `Waffo::Pancake.verify_webhook`
+    # and the Rails integration. Every value starts from its environment variable; the Railtie
+    # then applies `credentials.waffo`, and `Waffo::Pancake.configure` has the last word.
+    class Configuration
+      ENVIRONMENTS = %w[test prod].freeze
+
+      # MER_..., the API key's private key (PEM, PEM with literal \n, or bare base64), STO_...
+      attr_accessor :merchant_id, :private_key, :store_id
+      attr_accessor :base_url, :timeout, :logger
+      # A key used instead of the built-in platform keys; nil uses those.
+      attr_accessor :webhook_public_key
+      # Seconds a webhook timestamp may lie in the past (0 skips the check) or in the future.
+      attr_accessor :webhook_tolerance, :webhook_future_tolerance
+      # Anything answering `instrument(name, payload) { |payload| ... }`. Defaults to
+      # ActiveSupport::Notifications when it is loaded; nil turns instrumentation off.
+      attr_writer :instrumenter
+
+      # "test" or "prod": which platform key verifies webhooks, and which deliveries the Rails
+      # webhook concern accepts. nil tries prod, then test, and accepts both.
+      attr_reader :environment
+
+      def initialize
+        @merchant_id = ENV["WAFFO_MERCHANT_ID"]
+        @private_key = ENV["WAFFO_PRIVATE_KEY"]
+        @store_id = ENV["WAFFO_STORE_ID"]
+        begin
+          self.environment = ENV["WAFFO_ENVIRONMENT"]
+        rescue ConfigurationError => e
+          raise ConfigurationError, "WAFFO_ENVIRONMENT: #{e.message}"
+        end
+        @base_url = ENV["WAFFO_API_BASE_URL"] || Client::DEFAULT_BASE_URL
+        @timeout = Client::DEFAULT_TIMEOUT
+        @logger = nil
+        @webhook_public_key = nil
+        @webhook_tolerance = Webhook::DEFAULT_TOLERANCE
+        @webhook_future_tolerance = Webhook::DEFAULT_FUTURE_TOLERANCE
+        @instrumenter = :default
+      end
+
+      def environment=(value)
+        value = value.to_s.strip.downcase
+        value = nil if value.empty?
+        unless value.nil? || ENVIRONMENTS.include?(value)
+          raise ConfigurationError, "environment must be test or prod, got #{value.inspect}"
+        end
+
+        @environment = value
+      end
+
+      def instrumenter
+        return @instrumenter unless @instrumenter == :default
+
+        defined?(::ActiveSupport::Notifications) ? ::ActiveSupport::Notifications : nil
+      end
+
+      # What a client needs; a store id is only checked by the webhook concern.
+      def configured?
+        !blank?(merchant_id) && !blank?(private_key)
+      end
+
+      private
+        def blank?(value) = value.nil? || value.to_s.strip.empty?
+    end
+
+    @mutex = Mutex.new
+
+    class << self
+      def configuration
+        @configuration || @mutex.synchronize { @configuration ||= Configuration.new }
+      end
+
+      # Yields the configuration; the shared client is rebuilt on its next use.
+      def configure
+        yield configuration
+        reset_client!
+        configuration
+      end
+
+      # A client built from the configuration, shared by the process. Raises
+      # ConfigurationError while the merchant id or the key is missing.
+      def client
+        return @client if @client
+
+        config = configuration
+        @mutex.synchronize { @client ||= Client.new(config: config) }
+      end
+
+      # Replaces the shared client, for example with Waffo::Pancake::TestHelpers::FakeClient.
+      attr_writer :client
+
+      def reset_client!
+        @mutex.synchronize { @client = nil }
+      end
+
+      # Back to the environment variables, with no shared client.
+      def reset!
+        @mutex.synchronize do
+          @configuration = nil
+          @client = nil
+        end
+      end
+
+      # Webhook.verify with the configured environment, key and tolerances, reported as a
+      # `verify_webhook.waffo_pancake` event (with `:exception` when it is refused).
+      def verify_webhook(payload, signature_header, now: Time.now)
+        config = configuration
+        verify = lambda do |event_payload|
+          event = Webhook.verify(payload, signature_header, environment: config.environment,
+                                                            public_key: config.webhook_public_key,
+                                                            tolerance: config.webhook_tolerance,
+                                                            future_tolerance: config.webhook_future_tolerance, now: now)
+          event_payload.merge!(event_id: event["id"], event_type: event["eventType"], mode: event["mode"]) if event.is_a?(Hash)
+          event
+        end
+
+        instrumenter = config.instrumenter
+        details = { environment: config.environment }
+        instrumenter ? instrumenter.instrument("verify_webhook.waffo_pancake", details, &verify) : verify.call(details)
+      end
+    end
+  end
+end

data/lib/waffo/pancake/railtie.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module Waffo
+  module Pancake
+    # Loaded only inside a Rails app. Settings are applied in this order, the last one winning:
+    #
+    #   1. WAFFO_* environment variables
+    #   2. credentials.waffo (merchant_id, private_key, store_id, environment, webhook_public_key)
+    #   3. config.waffo_pancake.* in config/application.rb or an environment file
+    #   4. Waffo::Pancake.configure in config/initializers
+    #
+    # The logger defaults to Rails.logger, and `private_key` is filtered from logs.
+    class Railtie < ::Rails::Railtie
+      CREDENTIAL_KEYS = %i[merchant_id private_key store_id environment webhook_public_key].freeze
+
+      config.waffo_pancake = ActiveSupport::OrderedOptions.new
+
+      initializer "waffo_pancake.filter_parameters" do |app|
+        app.config.filter_parameters |= [:private_key]
+      end
+
+      initializer "waffo_pancake.configuration" do |app|
+        Waffo::Pancake.configure do |config|
+          credentials = app.credentials[:waffo] if app.respond_to?(:credentials)
+          CREDENTIAL_KEYS.each do |key|
+            value = credentials&.[](key)
+            config.public_send(:"#{key}=", value) unless value.nil? || value.to_s.strip.empty?
+          end
+
+          app.config.waffo_pancake.each { |key, value| config.public_send(:"#{key}=", value) }
+          config.logger ||= ::Rails.logger
+        end
+      end
+    end
+  end
+end

data/lib/waffo/pancake/test_helpers.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+require "waffo/pancake"
+
+module Waffo
+  module Pancake
+    # Helpers for an app's own tests (Minitest or RSpec):
+    #
+    #   # test/test_helper.rb                       # spec/rails_helper.rb
+    #   require "waffo/pancake/test_helpers"        require "waffo/pancake/test_helpers"
+    #   class ActiveSupport::TestCase               RSpec.configure do |config|
+    #     include Waffo::Pancake::TestHelpers         config.include Waffo::Pancake::TestHelpers
+    #   end                                         end
+    #
+    # `with_waffo_webhook_key` makes the configuration trust a throwaway key, and
+    # `waffo_webhook_headers` signs a body with it, so a request test can post a delivery the
+    # real verification accepts. `with_fake_waffo_client` swaps the shared client for a
+    # FakeClient, which records calls instead of making them.
+    module TestHelpers
+      # Generated once per process: RSA key generation is slow.
+      def self.key
+        @key ||= OpenSSL::PKey::RSA.generate(2048)
+      end
+
+      # Webhook verification trusts TestHelpers.key (and only it) inside the block.
+      def with_waffo_webhook_key(key = TestHelpers.key)
+        config = Waffo::Pancake.configuration
+        previous = config.webhook_public_key
+        config.webhook_public_key = key.public_key
+        yield
+      ensure
+        config.webhook_public_key = previous
+      end
+
+      # `t=<ms>,v1=<signature>` over the body, as Waffo sends it.
+      def waffo_webhook_signature(body, at: Time.now, key: TestHelpers.key)
+        timestamp = (at.to_f * 1000).to_i
+        signature = Base64.strict_encode64(key.sign(OpenSSL::Digest::SHA256.new, "#{timestamp}.#{body}"))
+        "t=#{timestamp},v1=#{signature}"
+      end
+
+      # Headers for posting `body` (a String) to a webhook endpoint.
+      def waffo_webhook_headers(body, **options)
+        { "CONTENT_TYPE" => "application/json", Webhook::SIGNATURE_HEADER => waffo_webhook_signature(body, **options) }
+      end
+
+      # A webhook envelope in Waffo's shape. `mode` and `store_id` default to the configuration.
+      def waffo_webhook_event(event_type, data: {}, id: SecureRandom.uuid, mode: nil, store_id: nil)
+        config = Waffo::Pancake.configuration
+        {
+          "id" => id,
+          "timestamp" => Time.now.utc.iso8601,
+          "eventType" => event_type,
+          "eventId" => "evt_#{SecureRandom.hex(8)}",
+          "storeId" => store_id || config.store_id || "STO_test",
+          "storeName" => "Test store",
+          "mode" => mode || config.environment || "test",
+          "data" => data
+        }
+      end
+
+      # Waffo::Pancake.client is `client` inside the block. Yields the client.
+      def with_fake_waffo_client(client = FakeClient.new)
+        previous = Waffo::Pancake.instance_variable_get(:@client)
+        Waffo::Pancake.client = client
+        yield client
+      ensure
+        Waffo::Pancake.client = previous
+      end
+
+      # Stands in for Waffo::Pancake::Client. Answers subscription_order from `orders`, moves
+      # an order's status on cancel / reactivate the way Waffo does, and records every call
+      # in `calls` as [method, arguments]. Set `fail_with` to an error to make calls raise it.
+      class FakeClient
+        attr_reader :orders, :calls
+        attr_accessor :fail_with, :checkout_url
+
+        def initialize(orders = {})
+          @orders = orders.transform_keys(&:to_s)
+          @calls = []
+          @checkout_url = "https://pancake.waffo.ai/store/test/checkout/cs_test"
+        end
+
+        def subscription_order(order_id)
+          record(:subscription_order, order_id)
+          order = @orders[order_id.to_s]
+          order && order.dup
+        end
+
+        def create_checkout_session(**params)
+          record(:create_checkout_session, params)
+          { "sessionId" => "cs_test", "checkoutUrl" => checkout_url, "expiresAt" => (Time.now + 2700).utc.iso8601 }
+        end
+
+        def create_authenticated_checkout(**params)
+          record(:create_authenticated_checkout, params)
+          { "sessionId" => "cs_test", "checkoutUrl" => "#{checkout_url}#token=test_token", "token" => "test_token",
+            "expiresAt" => (Time.now + 2700).utc.iso8601 }
+        end
+
+        def cancel_subscription(order_id)
+          record(:cancel_subscription, order_id)
+          change_status(order_id, "canceling")
+        end
+
+        def reactivate_subscription(order_id)
+          record(:reactivate_subscription, order_id)
+          change_status(order_id, "active")
+        end
+
+        def graphql(query, variables = {})
+          record(:graphql, query, variables)
+          {}
+        end
+
+        def action(path, params)
+          record(:action, path, params)
+          {}
+        end
+
+        def called?(name) = calls.any? { |call| call.first == name }
+
+        private
+          def record(name, *arguments)
+            calls << [name, *arguments]
+            raise fail_with if fail_with
+          end
+
+          def change_status(order_id, status)
+            @orders[order_id.to_s]&.merge!("status" => status)
+            { "orderId" => order_id, "status" => status }
+          end
+      end
+    end
+  end
+end

data/lib/waffo/pancake/version.rb

@@ -2,6 +2,6 @@
 
 module Waffo
   module Pancake
-    VERSION = "0.1.0"
+    VERSION = "0.2.1"
   end
 end

data/lib/waffo/pancake/webhook_controller.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Waffo
+  module Pancake
+    # Include in the controller that receives Waffo's webhooks:
+    #
+    #   class WaffoWebhooksController < ActionController::Base
+    #     include Waffo::Pancake::WebhookController
+    #
+    #     def create
+    #       HandleWaffoEventJob.perform_later(waffo_event)  # already verified
+    #       head :ok
+    #     end
+    #   end
+    #
+    # Before the action it reads the raw body, verifies X-Waffo-Signature with
+    # Waffo::Pancake.verify_webhook and exposes the event as `waffo_event`. A bad signature is
+    # answered 401 and an oversized body 413, without reaching the action. A delivery for
+    # another environment or store (when `environment` / `store_id` are configured) is
+    # acknowledged with 200 and skipped, since an error status only makes Waffo retry it.
+    #
+    # Deduplicate on `waffo_event["id"]`: a retry redelivers the same id.
+    module WebhookController
+      extend ActiveSupport::Concern
+
+      MAX_BODY_BYTES = 256 * 1024
+
+      included do
+        skip_forgery_protection if respond_to?(:skip_forgery_protection)
+        wrap_parameters false if respond_to?(:wrap_parameters)
+        before_action :verify_waffo_webhook!
+      end
+
+      # The body is trusted only once its signature checks out. Left to Rails it would be
+      # parsed into params first and written whole into the request log.
+      def process_action(...)
+        request.delete_header("action_dispatch.request.parameters")
+        request.request_parameters = {}
+        super
+      end
+
+      private
+        attr_reader :waffo_event
+
+        def verify_waffo_webhook!
+          body = request.body.read(MAX_BODY_BYTES + 1).to_s
+          request.body.rewind if request.body.respond_to?(:rewind)
+          return head(413) if body.bytesize > MAX_BODY_BYTES
+
+          @waffo_event = Waffo::Pancake.verify_webhook(body, request.headers[Webhook::SIGNATURE_HEADER])
+          return head(:bad_request) unless @waffo_event.is_a?(Hash) && @waffo_event["id"]
+          return if waffo_event_for_this_account?
+
+          waffo_webhook_log(:info, "skipped event=#{@waffo_event["id"]} mode=#{@waffo_event["mode"]} " \
+                                   "store=#{@waffo_event["storeId"]}: not this environment or store")
+          head :ok
+        rescue Waffo::Pancake::InvalidSignature => e
+          waffo_webhook_log(:warn, "refused: #{e.message}")
+          head :unauthorized
+        end
+
+        def waffo_event_for_this_account?
+          config = Waffo::Pancake.configuration
+          return false if config.environment && waffo_event["mode"] != config.environment
+
+          config.store_id.to_s.strip.empty? || waffo_event["storeId"] == config.store_id
+        end
+
+        def waffo_webhook_log(level, message)
+          (Waffo::Pancake.configuration.logger || logger)&.public_send(level, "[Waffo] webhook #{message}")
+        end
+    end
+  end
+end

data/lib/waffo/pancake.rb

@@ -5,9 +5,14 @@ require_relative "pancake/errors"
 require_relative "pancake/keys"
 require_relative "pancake/client"
 require_relative "pancake/webhook"
+require_relative "pancake/configuration"
+require_relative "pancake/railtie" if defined?(Rails::Railtie)
 
 module Waffo
   # Ruby client for the Waffo Pancake merchant API (https://docs.waffo.ai).
   module Pancake
+    # Need ActiveSupport / Action Pack; loaded on first use.
+    autoload :WebhookController, "waffo/pancake/webhook_controller"
+    autoload :TestHelpers, "waffo/pancake/test_helpers"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: waffo-pancake
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Good First Issue
@@ -34,12 +34,22 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- lib/generators/waffo_pancake/install/install_generator.rb
+- lib/generators/waffo_pancake/install/templates/create_waffo_webhook_events.rb.tt
+- lib/generators/waffo_pancake/install/templates/initializer.rb.tt
+- lib/generators/waffo_pancake/install/templates/webhook_event.rb.tt
+- lib/generators/waffo_pancake/install/templates/webhook_job.rb.tt
+- lib/generators/waffo_pancake/install/templates/webhooks_controller.rb.tt
 - lib/waffo/pancake.rb
 - lib/waffo/pancake/client.rb
+- lib/waffo/pancake/configuration.rb
 - lib/waffo/pancake/errors.rb
 - lib/waffo/pancake/keys.rb
+- lib/waffo/pancake/railtie.rb
+- lib/waffo/pancake/test_helpers.rb
 - lib/waffo/pancake/version.rb
 - lib/waffo/pancake/webhook.rb
+- lib/waffo/pancake/webhook_controller.rb
 homepage: https://github.com/goodfirstissueorg/waffo-pancake-ruby
 licenses:
 - MIT
@@ -63,7 +73,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Ruby client for the Waffo Pancake merchant API
 test_files: []