Countdown Timer API with Ruby on Rails

app/services/countdown.rb — public interface

# app/services/countdown.rb — standard library only.
require "net/http"
require "json"

class Countdown
  BASE = URI("https://countdownshare.com/api/v1")
  RETRYABLE = %w[rate_limited internal_error].freeze

  Error = Class.new(StandardError) do
    attr_reader :code, :status, :request_id, :retry_after

    def initialize(code:, message:, status:, request_id:, retry_after: nil)
      @code = code
      @status = status
      @request_id = request_id
      @retry_after = retry_after
      super("#{code}: #{message} (#{request_id})")
    end
  end

  def initialize(api_key: ENV.fetch("COUNTDOWNSHARE_API_KEY"))
    @api_key = api_key
  end

  def create_timer(body, idempotency_key:)
    with_retry do
      post("/timers", body, "Idempotency-Key" => idempotency_key)
    end
  end

  def status(timer_id)
    get("/timers/#{timer_id}/status")
  end

  def outputs(timer_id)
    get("/timers/#{timer_id}/outputs")
  end

  private

  def with_retry(attempts: 4)
    attempt = 0
    begin
      yield
    rescue Error => e
      attempt += 1
      raise if !RETRYABLE.include?(e.code) || attempt >= attempts

      sleep(e.retry_after || [2**attempt * 0.5, 8].min)
      retry
    end
  end

app/services/countdown.rb — transport

  def get(path)
    request(Net::HTTP::Get.new(uri_for(path)))
  end

  def post(path, body, headers = {})
    req = Net::HTTP::Post.new(uri_for(path))
    headers.each { |k, v| req[k] = v }
    req.body = body.to_json
    request(req)
  end

  def uri_for(path)
    URI("#{BASE}#{path}")
  end

  def request(req)
    req["Authorization"] = "Bearer #{@api_key}"
    req["Content-Type"] = "application/json"

    response = Net::HTTP.start(
      req.uri.host, req.uri.port, use_ssl: true, read_timeout: 10
    ) { |http| http.request(req) }

    payload = JSON.parse(response.body)

    unless response.is_a?(Net::HTTPSuccess)
      raise Error.new(
        code: payload.dig("error", "code"),
        message: payload.dig("error", "message"),
        status: response.code.to_i,
        request_id: payload["request_id"],
        retry_after: response["Retry-After"]&.to_i,
      )
    end

    payload["data"]
  end
end

config/routes.rb

# config/routes.rb
post "/webhooks/countdownshare", to: "countdown_webhooks#create"

app/controllers/countdown_webhooks_controller.rb

# app/controllers/countdown_webhooks_controller.rb
class CountdownWebhooksController < ActionController::API
  # ActionController::API has no forgery protection, which is what
  # you want here. If you inherit from ApplicationController instead,
  # add: skip_before_action :verify_authenticity_token

  def create
    # request.raw_post is the RAW body. params is parsed and
    # cannot be turned back into the bytes that were signed.
    raw = request.raw_post

    return head :unauthorized unless verified?(raw)

    event = JSON.parse(raw)

    # Enqueue and return. The delivery is treated as a timeout
    # after ten seconds.
    HandleCountdownEventJob.perform_later(event)

    head :ok
  end

  private

  def verified?(raw)
    timestamp = request.headers["X-CountdownShare-Timestamp"]
    signature = request.headers["X-CountdownShare-Signature"]
    return false if timestamp.blank? || signature.blank?

    # Reject anything older than five minutes.
    return false if (Time.now.to_i - timestamp.to_i).abs > 300

    expected = OpenSSL::HMAC.hexdigest(
      "SHA256",
      Rails.application.credentials.countdownshare_webhook_secret,
      "#{timestamp}.#{raw}",
    )

    # secure_compare is constant time; == is not.
    ActiveSupport::SecurityUtils.secure_compare(
      expected, signature.delete_prefix("v1=")
    )
  end
end