fizzy-sdk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 335822e6052678da32698d8c2546640f4e78535904305e39ab64a83aec2abf16
+  data.tar.gz: e2e54f187ed12c89fb07862b30595a345bf611508cd0283302369d0708f17ee2
+SHA512:
+  metadata.gz: c462ced9ffa65dc73febf9b6c42d16264b4decb68374185e3db4f0affe58420e3712f824a8e64581ed08c260982f6de671be915697d76c6322fd2378a18e2b94
+  data.tar.gz: ec9026294b2270549849c08fbbc09758f9fceb636b9640f8bbbced9b4c820250a036e83529bd0e05c7c4fc1350065f41d1bbb608ea39a972b1c06f75d0d087bd

data/.rubocop.yml

@@ -0,0 +1,18 @@
+# 37signals house style
+inherit_gem:
+  rubocop-37signals: rubocop.yml
+
+AllCops:
+  TargetRubyVersion: 3.2
+  Exclude:
+    - "vendor/**/*"
+    - "lib/fizzy/generated/**/*"
+
+# Documentation not required for tests
+Style/Documentation:
+  Exclude:
+    - "test/**/*"
+
+# This gem uses Minitest (not Rails), so refute is correct
+Rails/RefuteMethods:
+  Enabled: false

data/Rakefile

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+require 'rubocop/rake_task'
+require 'yard'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+RuboCop::RakeTask.new
+
+YARD::Rake::YardocTask.new(:doc) do |t|
+  t.files = [ 'lib/**/*.rb' ]
+  t.options = [ '--output-dir', 'doc' ]
+end
+
+desc 'Start an interactive console with the SDK loaded'
+task :console do
+  exec 'bin/console'
+end
+
+task default: %i[test rubocop]

data/fizzy-sdk.gemspec

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative 'lib/fizzy/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'fizzy-sdk'
+  spec.version = Fizzy::VERSION
+  spec.authors = [ 'Basecamp' ]
+  spec.email = [ 'support@basecamp.com' ]
+
+  spec.summary = 'Official Ruby SDK for the Fizzy API'
+  spec.description = 'A Ruby SDK for the Fizzy API with automatic retry, ' \
+                     'exponential backoff, Link header pagination, and observability hooks.'
+  spec.homepage = 'https://github.com/basecamp/fizzy-sdk'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.2.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/releases"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+  spec.require_paths = [ 'lib' ]
+
+  # Runtime dependencies
+  spec.add_dependency 'faraday', '~> 2.0'
+  spec.add_dependency 'zeitwerk', '~> 2.6'
+
+  # Development dependencies
+  spec.add_development_dependency 'minitest', '~> 6.0'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rubocop-37signals'
+  spec.add_development_dependency 'simplecov', '~> 0.22'
+  spec.add_development_dependency 'webmock', '~> 3.24'
+  spec.add_development_dependency 'irb', '~> 1.15'
+  spec.add_development_dependency 'rdoc', '~> 7.1'
+  spec.add_development_dependency 'webrick', '~> 1.9'
+  spec.add_development_dependency 'yard', '~> 0.9'
+end

data/lib/fizzy/auth_strategy.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Fizzy
+  # AuthStrategy controls how authentication is applied to HTTP requests.
+  # The default strategy is BearerAuth, which uses a TokenProvider to set
+  # the Authorization header with a Bearer token.
+  #
+  # Custom strategies can implement alternative auth schemes such as
+  # cookie-based auth or magic link flows.
+  #
+  # To implement a custom strategy, create a class that responds to
+  # #authenticate(headers), where headers is a Hash that you can modify.
+  module AuthStrategy
+    # Apply authentication to the given headers hash.
+    # @param headers [Hash] the request headers to modify
+    def authenticate(headers)
+      raise NotImplementedError, "#{self.class} must implement #authenticate"
+    end
+  end
+
+  # Bearer token authentication strategy (default).
+  # Sets the Authorization header with "Bearer {token}".
+  class BearerAuth
+    include AuthStrategy
+
+    # @param token_provider [TokenProvider] provides access tokens
+    def initialize(token_provider)
+      @token_provider = token_provider
+    end
+
+    # @return [TokenProvider] the underlying token provider
+    attr_reader :token_provider
+
+    def authenticate(headers)
+      headers["Authorization"] = "Bearer #{@token_provider.access_token}"
+    end
+  end
+end

data/lib/fizzy/bulkhead.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Fizzy
+  # Semaphore-based concurrency limiter (bulkhead pattern).
+  #
+  # Limits the number of concurrent operations to prevent resource exhaustion.
+  # When the limit is reached, callers block until a slot becomes available
+  # or the timeout expires.
+  #
+  # @example
+  #   bulkhead = Fizzy::Bulkhead.new(max_concurrent: 10, timeout: 5)
+  #   bulkhead.call { http.get("/boards") }
+  class Bulkhead
+    # @param max_concurrent [Integer] maximum concurrent operations
+    # @param timeout [Numeric] seconds to wait for a slot (0 = fail immediately)
+    def initialize(max_concurrent: 10, timeout: 5)
+      @max_concurrent = max_concurrent
+      @timeout = timeout
+      @semaphore = Mutex.new
+      @condition = ConditionVariable.new
+      @current = 0
+    end
+
+    # @return [Integer] number of currently active operations
+    attr_reader :current
+
+    # Executes the block within the concurrency limit.
+    #
+    # @yield the operation to execute
+    # @return the result of the block
+    # @raise [Fizzy::APIError] if no slot is available within timeout
+    def call
+      acquire_slot
+      begin
+        yield
+      ensure
+        release_slot
+      end
+    end
+
+    private
+
+    def acquire_slot
+      deadline = Time.now + @timeout
+
+      @semaphore.synchronize do
+        while @current >= @max_concurrent
+          remaining = deadline - Time.now
+          if remaining <= 0
+            raise Fizzy::APIError.new(
+              "Bulkhead limit reached (#{@max_concurrent} concurrent)",
+              hint: "Too many concurrent requests, try again later"
+            )
+          end
+          @condition.wait(@semaphore, remaining)
+        end
+        @current += 1
+      end
+    end
+
+    def release_slot
+      @semaphore.synchronize do
+        @current -= 1
+        @condition.signal
+      end
+    end
+  end
+end

data/lib/fizzy/cache.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "fileutils"
+
+module Fizzy
+  # ETag-based HTTP cache for GET requests (file-based, opt-in).
+  #
+  # Stores responses keyed by URL with ETag validation. On cache hit with
+  # matching ETag, returns 304 Not Modified without re-downloading the body.
+  #
+  # @example
+  #   cache = Fizzy::Cache.new(dir: "/tmp/fizzy-cache")
+  #   # Used internally by Http when cache is configured
+  class Cache
+    # @param dir [String] directory for cache files
+    # @param max_entries [Integer] maximum cache entries before eviction
+    def initialize(dir:, max_entries: 1000)
+      @dir = dir
+      @max_entries = max_entries
+      FileUtils.mkdir_p(@dir)
+    end
+
+    # Returns cached response headers for conditional request.
+    # @param url [String] the request URL
+    # @return [Hash, nil] headers with If-None-Match if cached
+    def conditional_headers(url)
+      entry = read_entry(url)
+      return nil unless entry
+
+      { "If-None-Match" => entry["etag"] }
+    end
+
+    # Stores a response in the cache.
+    # @param url [String] the request URL
+    # @param etag [String] the ETag header value
+    # @param body [String] the response body
+    def store(url, etag:, body:)
+      return if etag.nil? || etag.empty?
+
+      evict_if_full
+
+      entry = {
+        "etag" => etag,
+        "body" => body,
+        "cached_at" => Time.now.to_i
+      }
+
+      path = entry_path(url)
+      File.write(path, JSON.generate(entry))
+    end
+
+    # Returns cached body if available.
+    # @param url [String] the request URL
+    # @return [String, nil] the cached body
+    def get(url)
+      entry = read_entry(url)
+      entry&.dig("body")
+    end
+
+    # Invalidates a cache entry.
+    # @param url [String] the request URL
+    def invalidate(url)
+      path = entry_path(url)
+      File.delete(path) if File.exist?(path)
+    end
+
+    # Clears the entire cache.
+    def clear
+      Dir.glob(File.join(@dir, "*.json")).each { |f| File.delete(f) }
+    end
+
+    private
+
+    def entry_path(url)
+      key = Digest::SHA256.hexdigest(url)
+      File.join(@dir, "#{key}.json")
+    end
+
+    def read_entry(url)
+      path = entry_path(url)
+      return nil unless File.exist?(path)
+
+      JSON.parse(File.read(path))
+    rescue JSON::ParserError
+      File.delete(path)
+      nil
+    end
+
+    def evict_if_full
+      entries = Dir.glob(File.join(@dir, "*.json"))
+      return if entries.length < @max_entries
+
+      # Evict oldest entries (by mtime)
+      entries.sort_by { |f| File.mtime(f) }
+             .first(entries.length - @max_entries + 1)
+             .each { |f| File.delete(f) }
+    end
+  end
+end

data/lib/fizzy/chain_hooks.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Fizzy
+  # Composes multiple Hooks implementations, calling them in sequence.
+  # Start events are called in order; end events are called in reverse order.
+  class ChainHooks
+    include Hooks
+
+    def initialize(*hooks)
+      @hooks = hooks
+    end
+
+    def on_operation_start(info)
+      @hooks.each { |h| safe_call { h.on_operation_start(info) } }
+    end
+
+    def on_operation_end(info, result)
+      @hooks.reverse_each { |h| safe_call { h.on_operation_end(info, result) } }
+    end
+
+    def on_request_start(info)
+      @hooks.each { |h| safe_call { h.on_request_start(info) } }
+    end
+
+    def on_request_end(info, result)
+      @hooks.reverse_each { |h| safe_call { h.on_request_end(info, result) } }
+    end
+
+    def on_retry(info, attempt, error, delay)
+      @hooks.each { |h| safe_call { h.on_retry(info, attempt, error, delay) } }
+    end
+
+    def on_paginate(url, page)
+      @hooks.each { |h| safe_call { h.on_paginate(url, page) } }
+    end
+
+    private
+
+    def safe_call
+      yield
+    rescue => e
+      warn "Fizzy::ChainHooks: hook raised #{e.class}: #{e.message}"
+    end
+  end
+end

data/lib/fizzy/circuit_breaker.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Fizzy
+  # Circuit breaker pattern for fault tolerance.
+  #
+  # Tracks consecutive failures and opens the circuit when the threshold is
+  # reached, preventing further requests until the recovery timeout expires.
+  #
+  # States:
+  # - :closed  -- normal operation, requests flow through
+  # - :open    -- circuit tripped, requests fail immediately
+  # - :half_open -- recovery probe, single request allowed through
+  #
+  # @example
+  #   breaker = Fizzy::CircuitBreaker.new(threshold: 5, timeout: 30)
+  #   breaker.call { http.get("/boards") }
+  class CircuitBreaker
+    # @param threshold [Integer] consecutive failures before opening
+    # @param timeout [Numeric] seconds to wait before half-open probe
+    def initialize(threshold: 5, timeout: 30)
+      @threshold = threshold
+      @timeout = timeout
+      @failure_count = 0
+      @last_failure_at = nil
+      @state = :closed
+      @mutex = Mutex.new
+    end
+
+    # @return [Symbol] current circuit state (:closed, :open, :half_open)
+    def state
+      @mutex.synchronize { effective_state }
+    end
+
+    # Executes the block through the circuit breaker.
+    #
+    # @yield the operation to protect
+    # @return the result of the block
+    # @raise [Fizzy::APIError] if circuit is open
+    def call
+      half_open_probe = false
+
+      @mutex.synchronize do
+        case effective_state
+        when :open
+          raise Fizzy::APIError.new(
+            "Circuit breaker is open",
+            retryable: true,
+            hint: "Service appears unavailable, will retry after #{@timeout}s"
+          )
+        when :half_open
+          half_open_probe = true
+          @state = :half_open
+        end
+      end
+
+      if half_open_probe
+        # Single-probe: hold the probe flag so concurrent callers see :half_open
+        # and block (they'll see :open until this probe completes).
+        @mutex.synchronize { @state = :open }
+        begin
+          result = yield
+          record_success
+          return result
+        rescue Fizzy::NetworkError, Fizzy::APIError => e
+          record_failure if e.retryable?
+          raise
+        end
+      end
+
+      begin
+        result = yield
+        record_success
+        result
+      rescue Fizzy::NetworkError, Fizzy::APIError => e
+        record_failure if e.retryable?
+        raise
+      end
+    end
+
+    # Resets the circuit breaker to closed state.
+    def reset
+      @mutex.synchronize do
+        @failure_count = 0
+        @last_failure_at = nil
+        @state = :closed
+      end
+    end
+
+    private
+
+    def effective_state
+      if @state == :open && @last_failure_at && \
+         (Time.now - @last_failure_at) >= @timeout
+        :half_open
+      else
+        @state
+      end
+    end
+
+    def record_success
+      @mutex.synchronize do
+        @failure_count = 0
+        @state = :closed
+      end
+    end
+
+    def record_failure
+      @mutex.synchronize do
+        @failure_count += 1
+        @last_failure_at = Time.now
+        @state = :open if @failure_count >= @threshold
+      end
+    end
+  end
+end

data/lib/fizzy/client.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module Fizzy
+  # Main client for the Fizzy API.
+  #
+  # Client holds shared resources and provides service accessors for all
+  # 15 Fizzy services. Unlike Basecamp's Client -> AccountClient pattern,
+  # Fizzy does not require an account ID -- all services are available
+  # directly on the Client.
+  #
+  # @example Basic usage
+  #   config = Fizzy::Config.from_env
+  #   token_provider = Fizzy::StaticTokenProvider.new(ENV["FIZZY_ACCESS_TOKEN"])
+  #   client = Fizzy::Client.new(config: config, token_provider: token_provider)
+  #
+  #   boards = client.boards.list.to_a
+  #   card = client.cards.get(board_id: 1, card_id: 42)
+  #
+  # @example With custom hooks
+  #   require "logger"
+  #   logger = Logger.new($stdout)
+  #   hooks = Fizzy::LoggerHooks.new(logger)
+  #
+  #   client = Fizzy::Client.new(
+  #     config: config,
+  #     token_provider: token_provider,
+  #     hooks: hooks
+  #   )
+  class Client
+    # @return [Config] client configuration
+    attr_reader :config
+
+    # Creates a new Fizzy API client.
+    #
+    # @param config [Config] configuration settings
+    # @param token_provider [TokenProvider, nil] token provider (deprecated, use auth_strategy)
+    # @param auth_strategy [AuthStrategy, nil] authentication strategy
+    # @param hooks [Hooks, nil] observability hooks
+    def initialize(config:, token_provider: nil, auth_strategy: nil, hooks: nil)
+      raise ArgumentError, "provide either token_provider or auth_strategy, not both" if token_provider && auth_strategy
+      raise ArgumentError, "provide token_provider or auth_strategy" if !token_provider && !auth_strategy
+
+      @config = config
+      @hooks = hooks || NoopHooks.new
+      @http = Http.new(config: config, token_provider: token_provider, auth_strategy: auth_strategy, hooks: @hooks)
+      @services = {}
+      @mutex = Mutex.new
+    end
+
+    # @api private
+    # Returns the HTTP client for making requests.
+    # @return [Http]
+    attr_reader :http
+
+    # @api private
+    # Returns the observability hooks.
+    # @return [Hooks]
+    attr_reader :hooks
+
+    # Performs a GET request.
+    # @param path [String] URL path
+    # @param params [Hash] query parameters
+    # @return [Response]
+    def get(path, params: {})
+      @http.get(path, params: params)
+    end
+
+    # Performs a POST request.
+    # @param path [String] URL path
+    # @param body [Hash, nil] request body
+    # @param retryable [Boolean, nil] override retry behavior (true for idempotent POSTs)
+    # @return [Response]
+    def post(path, body: nil, retryable: nil)
+      @http.post(path, body: body, retryable: retryable)
+    end
+
+    # Performs a PUT request.
+    # @param path [String] URL path
+    # @param body [Hash, nil] request body
+    # @return [Response]
+    def put(path, body: nil)
+      @http.put(path, body: body)
+    end
+
+    # Performs a PATCH request.
+    # @param path [String] URL path
+    # @param body [Hash, nil] request body
+    # @return [Response]
+    def patch(path, body: nil)
+      @http.patch(path, body: body)
+    end
+
+    # Performs a DELETE request.
+    # @param path [String] URL path
+    # @param retryable [Boolean, nil] override retry behavior
+    # @return [Response]
+    def delete(path, retryable: nil)
+      @http.delete(path, retryable: retryable)
+    end
+
+    # Performs a POST request with raw binary data.
+    # Used for file uploads.
+    # @param path [String] URL path
+    # @param body [String, IO] raw binary data
+    # @param content_type [String] MIME content type
+    # @return [Response]
+    def post_raw(path, body:, content_type:)
+      @http.post_raw(path, body: body, content_type: content_type)
+    end
+
+    # Fetches all pages of a paginated resource.
+    # @param path [String] URL path
+    # @param params [Hash] query parameters
+    # @yield [Hash] each item from the response
+    # @return [Enumerator] if no block given
+    def paginate(path, params: {}, &)
+      @http.paginate(path, params: params, &)
+    end
+
+    # @!group Services
+
+    # @return [Services::IdentityService]
+    def identity
+      service(:identity) { Services::IdentityService.new(self) }
+    end
+
+    # @return [Services::BoardsService]
+    def boards
+      service(:boards) { Services::BoardsService.new(self) }
+    end
+
+    # @return [Services::ColumnsService]
+    def columns
+      service(:columns) { Services::ColumnsService.new(self) }
+    end
+
+    # @return [Services::CardsService]
+    def cards
+      service(:cards) { Services::CardsService.new(self) }
+    end
+
+    # @return [Services::CommentsService]
+    def comments
+      service(:comments) { Services::CommentsService.new(self) }
+    end
+
+    # @return [Services::StepsService]
+    def steps
+      service(:steps) { Services::StepsService.new(self) }
+    end
+
+    # @return [Services::ReactionsService]
+    def reactions
+      service(:reactions) { Services::ReactionsService.new(self) }
+    end
+
+    # @return [Services::NotificationsService]
+    def notifications
+      service(:notifications) { Services::NotificationsService.new(self) }
+    end
+
+    # @return [Services::TagsService]
+    def tags
+      service(:tags) { Services::TagsService.new(self) }
+    end
+
+    # @return [Services::UsersService]
+    def users
+      service(:users) { Services::UsersService.new(self) }
+    end
+
+    # @return [Services::PinsService]
+    def pins
+      service(:pins) { Services::PinsService.new(self) }
+    end
+
+    # @return [Services::UploadsService]
+    def uploads
+      service(:uploads) { Services::UploadsService.new(self) }
+    end
+
+    # @return [Services::WebhooksService]
+    def webhooks
+      service(:webhooks) { Services::WebhooksService.new(self) }
+    end
+
+    # @return [Services::SessionsService]
+    def sessions
+      service(:sessions) { Services::SessionsService.new(self) }
+    end
+
+    # @return [Services::DevicesService]
+    def devices
+      service(:devices) { Services::DevicesService.new(self) }
+    end
+
+    # @return [Services::MiscellaneousService]
+    def miscellaneous
+      service(:miscellaneous) { Services::MiscellaneousService.new(self) }
+    end
+
+    # @!endgroup
+
+    private
+
+    def service(name)
+      @mutex.synchronize do
+        @services[name] ||= yield
+      end
+    end
+  end
+end