garde_fou 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 878ca8aa7468ba775feda57eca93eab7d79a60a97a9a4efecf33e568b0c778e3
+  data.tar.gz: 3b36234d3c4abc60427ba78f754a57dae007c337fee7a72671fbbfc9eb647ca2
+SHA512:
+  metadata.gz: bf8468be03ec6c46314b56d6a7ca10b48af96e1964d2be80841f3629f244ac67390fc2ba96a9858a106d701f1162410ccbe1c6001b50cde012647b0b5c4c6bfd
+  data.tar.gz: f3bcf50270bd78ddd735e6e9b6750c2c1a1244a8d9b62f99a7d84799f40c5544f8b64d515630427b7f28508d240bde3408195089a25989dae14d41b57872e42a

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# 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).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-07-19
+
+### Added
+- Initial Ruby implementation of garde-fou
+- Call counting with configurable limits
+- Duplicate call detection
+- Multiple calling patterns (call, [], protect)
+- Flexible violation handlers (warn, raise, custom procs)
+- Configuration loading from JSON/YAML files
+- GuardedClient mixin for class-level protection
+- Comprehensive test suite with RSpec
+- Ruby-idiomatic API design
+
+[Unreleased]: https://github.com/rfievet/garde-fou/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/rfievet/garde-fou/releases/tag/v0.1.0

data/README.md

@@ -0,0 +1,284 @@
+# garde-fou (Ruby)
+
+[![Gem Version](https://badge.fury.io/rb/garde_fou.svg)](https://badge.fury.io/rb/garde_fou)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**garde-fou** is a lightweight guard for protecting against accidental over-usage of paid API calls. It provides call counting and duplicate detection to help you avoid unexpected API bills.
+
+## Features
+
+- **Call counting** - Set maximum number of calls and get warnings or exceptions when exceeded
+- **Duplicate detection** - Detect and handle repeated identical API calls
+- **Flexible violation handling** - Choose to warn, raise exceptions, or use custom handlers
+- **Configuration support** - Load settings from JSON/YAML files or set programmatically
+- **Multiple calling patterns** - Ruby-idiomatic syntax with multiple ways to call
+- **Mixin support** - Include GuardedClient module for class-level protection
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'garde_fou'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install garde_fou
+
+## Quick Start
+
+```ruby
+require 'gardefou'
+
+# Create a guard with call limits
+guard = Gardefou::GardeFou.new(max_calls: 5, on_violation_max_calls: 'warn')
+
+# Multiple calling patterns available:
+# 1. Method call (explicit)
+result = guard.call(your_api_method, "your", "arguments")
+
+# 2. Bracket syntax (Ruby callable style)
+result = guard[your_api_method, "your", "arguments"]
+
+# 3. Protect method (semantic)
+result = guard.protect(your_api_method, "your", "arguments")
+```
+
+## Usage Examples
+
+### Basic Call Limiting
+```ruby
+require 'gardefou'
+
+# Create a guard with a 3-call limit
+guard = Gardefou::GardeFou.new(max_calls: 3, on_violation_max_calls: 'raise')
+
+begin
+  # All calling patterns work identically
+  guard.call(api_method, 'query 1')
+  guard[api_method, 'query 2']
+  guard.protect(api_method, 'query 3')
+  guard.call(api_method, 'query 4')  # This will raise!
+rescue Gardefou::QuotaExceededError => e
+  puts "Call limit exceeded: #{e.message}"
+end
+```
+
+### Duplicate Call Detection
+```ruby
+# Warn on duplicate calls
+guard = Gardefou::GardeFou.new(on_violation_duplicate_call: 'warn')
+
+guard.call(api_method, 'hello')  # First call - OK
+guard.call(api_method, 'hello')  # Duplicate - Warning printed
+guard.call(api_method, 'world')  # Different call - OK
+```
+
+### Using Profiles
+```ruby
+# Create a profile with multiple rules
+profile = Gardefou::Profile.new(
+  max_calls: 10,
+  on_violation_max_calls: 'raise',
+  on_violation_duplicate_call: 'warn'
+)
+
+guard = Gardefou::GardeFou.new(profile: profile)
+```
+
+### Configuration Files
+```ruby
+# Load from JSON/YAML file
+profile = Gardefou::Profile.new(config: 'gardefou.config.json')
+guard = Gardefou::GardeFou.new(profile: profile)
+
+# Or pass config as hash
+config = { 'max_calls' => 5, 'on_violation_max_calls' => 'warn' }
+profile = Gardefou::Profile.new(config: config)
+```
+
+### Custom Violation Handlers
+```ruby
+custom_handler = proc do |profile|
+  puts "Custom violation! Call count: #{profile.call_count}"
+  # Send alert, log to service, etc.
+end
+
+guard = Gardefou::GardeFou.new(
+  max_calls: 5,
+  on_violation_max_calls: custom_handler
+)
+
+# All calling patterns work with custom handlers
+guard.call(api_method, 'test')      # Method call
+guard[api_method, 'test']           # Bracket syntax
+guard.protect(api_method, 'test')   # Protect method
+```
+
+### Using the GuardedClient Mixin
+```ruby
+class APIClient
+  include Gardefou::GuardedClient
+  
+  def expensive_call(query)
+    # Your expensive API call here
+    "Result for #{query}"
+  end
+  
+  def another_call(data)
+    # Another API call
+    "Processed #{data}"
+  end
+  
+  # Guard specific methods
+  guard_method :expensive_call, max_calls: 10, on_violation_max_calls: 'warn'
+  
+  # Guard all methods matching a pattern
+  guard_methods /call$/, max_calls: 5, on_violation_duplicate_call: 'warn'
+end
+
+client = APIClient.new
+client.expensive_call('test')  # Protected automatically
+```
+
+## Real-World Examples
+
+### OpenAI API Protection
+```ruby
+require 'gardefou'
+
+# Assuming you have an OpenAI client
+guard = Gardefou::GardeFou.new(
+  max_calls: 100,
+  on_violation_max_calls: 'warn',
+  on_violation_duplicate_call: 'warn'
+)
+
+# Before: Direct API call
+# response = openai_client.completions(prompt: 'Hello!')
+
+# After: Protected API call (choose your preferred syntax)
+response = guard.call(openai_client.method(:completions), prompt: 'Hello!')
+# or
+response = guard[openai_client.method(:completions), prompt: 'Hello!']
+# or  
+response = guard.protect(openai_client.method(:completions), prompt: 'Hello!')
+```
+
+### Multiple API Services
+```ruby
+guard = Gardefou::GardeFou.new(max_calls: 50)
+
+# Protect different APIs with the same guard
+openai_result = guard.call(openai_client.method(:completions), prompt: 'test')
+anthropic_result = guard[anthropic_client.method(:messages), message: 'test']
+cohere_result = guard.protect(cohere_client.method(:generate), text: 'test')
+
+puts "Total API calls made: #{guard.profile.call_count}"
+```
+
+## Configuration Options
+
+- `max_calls`: Maximum number of calls allowed (-1 for unlimited)
+- `on_violation_max_calls`: Handler when call limit exceeded (`'warn'`, `'raise'`, or Proc)
+- `on_violation_duplicate_call`: Handler for duplicate calls (`'warn'`, `'raise'`, or Proc)
+- `on_violation`: Default handler for all violations
+
+## API Reference
+
+### GardeFou Class
+
+#### Constructor
+```ruby
+Gardefou::GardeFou.new(
+  profile: nil,
+  max_calls: nil,
+  on_violation: nil,
+  on_violation_max_calls: nil,
+  on_violation_duplicate_call: nil
+)
+```
+
+#### Methods
+- `call(method, *args, **kwargs, &block)` - Execute a method with protection
+- `[method, *args, **kwargs, &block]` - Ruby callable syntax (alias for call)
+- `protect(method, *args, **kwargs, &block)` - Semantic alias for call
+
+### Profile Class
+
+#### Constructor
+```ruby
+Gardefou::Profile.new(
+  config: nil,
+  max_calls: nil,
+  on_violation: nil,
+  on_violation_max_calls: nil,
+  on_violation_duplicate_call: nil
+)
+```
+
+### GuardedClient Module
+
+#### Class Methods
+- `guard_method(method_name, **options)` - Guard a specific method
+- `guard_methods(pattern, **options)` - Guard methods matching a pattern
+
+#### Instance Methods
+- `create_guard(**options)` - Create an instance-level guard
+
+## How It Works
+
+garde-fou works by wrapping your method calls. Instead of calling your API method directly, you call it through the guard:
+
+```ruby
+# Before
+result = openai_client.completions(prompt: 'Hello!')
+
+# After - choose your preferred syntax:
+guard = Gardefou::GardeFou.new(max_calls: 10)
+
+# Option 1: Method call
+result = guard.call(openai_client.method(:completions), prompt: 'Hello!')
+
+# Option 2: Bracket syntax (Ruby callable style)
+result = guard[openai_client.method(:completions), prompt: 'Hello!']
+
+# Option 3: Protect method (semantic)
+result = guard.protect(openai_client.method(:completions), prompt: 'Hello!')
+```
+
+The guard tracks calls and enforces your configured rules before executing the actual method.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+rake spec
+
+# Run example
+rake example
+
+# Run RuboCop
+rake rubocop
+
+# Run all checks
+rake check
+```
+
+## Contributing
+
+This is part of the multi-language garde-fou toolkit. See the main repository for contributing guidelines.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/gardefou/garde_fou.rb

@@ -0,0 +1,52 @@
+require_relative 'profile'
+
+module Gardefou
+  class GardeFou
+    attr_reader :profile
+
+    def initialize(profile: nil, **profile_options)
+      @profile = profile || Profile.new(**profile_options)
+    end
+
+    # Main callable interface - allows guard.call(method, *args, **kwargs)
+    def call(method, *args, **kwargs, &block)
+      # Extract method name for tracking
+      method_name = extract_method_name(method)
+
+      # Run profile checks
+      @profile.check(method_name, args, kwargs)
+
+      # Execute the method
+      if kwargs.empty?
+        # Ruby 2.6 compatibility - avoid passing empty kwargs
+        method.call(*args, &block)
+      else
+        method.call(*args, **kwargs, &block)
+      end
+    end
+
+    # Ruby-style callable interface - allows guard.(method, *args, **kwargs)
+    # This is Ruby's equivalent to Python's __call__
+    alias [] call
+
+    # Alternative syntax for those who prefer it
+    def protect(method, *args, **kwargs, &block)
+      call(method, *args, **kwargs, &block)
+    end
+
+    private
+
+    def extract_method_name(method)
+      case method
+      when Method
+        "#{method.receiver.class}##{method.name}"
+      when UnboundMethod
+        "#{method.owner}##{method.name}"
+      when Proc
+        method.source_location ? "Proc@#{method.source_location.join(':')}" : 'Proc'
+      else
+        method.class.name
+      end
+    end
+  end
+end

data/lib/gardefou/profile.rb

@@ -0,0 +1,96 @@
+require 'json'
+require 'yaml'
+
+module Gardefou
+  class QuotaExceededError < StandardError; end
+
+  class Profile
+    attr_reader :max_calls, :on_violation, :on_violation_max_calls, :on_violation_duplicate_call, :call_count
+
+    def initialize(config: nil, max_calls: nil, on_violation: nil,
+                   on_violation_max_calls: nil, on_violation_duplicate_call: nil)
+      # Load base data from file or hash
+      data = {}
+
+      if config.is_a?(String)
+        # Load from file
+        content = File.read(config)
+        data = if config.end_with?('.yaml', '.yml')
+                 YAML.safe_load(content)
+               else
+                 JSON.parse(content)
+               end
+      elsif config.is_a?(Hash)
+        data = config.dup
+      end
+
+      # Override with explicit options
+      data['max_calls'] = max_calls unless max_calls.nil?
+      data['on_violation'] = on_violation unless on_violation.nil?
+      data['on_violation_max_calls'] = on_violation_max_calls unless on_violation_max_calls.nil?
+      data['on_violation_duplicate_call'] = on_violation_duplicate_call unless on_violation_duplicate_call.nil?
+
+      # Assign settings with defaults
+      @max_calls = data['max_calls'] || -1
+      @on_violation = data['on_violation'] || 'raise'
+      @on_violation_max_calls = data['on_violation_max_calls'] || @on_violation
+      @on_violation_duplicate_call = data['on_violation_duplicate_call'] || @on_violation
+
+      @call_count = 0
+      @call_signatures = Set.new
+
+      # Track which rules were explicitly configured
+      @max_calls_enabled = data.key?('max_calls') && @max_calls >= 0
+      @dup_enabled = data.key?('on_violation_duplicate_call')
+    end
+
+    def check(fn_name = nil, args = [], kwargs = {})
+      check_max_call if @max_calls_enabled
+      check_duplicate(fn_name, args, kwargs) if @dup_enabled
+    end
+
+    private
+
+    def check_max_call
+      @call_count += 1
+      return unless @call_count > @max_calls
+
+      msg = "GardeFou: call quota exceeded (#{@call_count}/#{@max_calls})"
+      handle_violation(@on_violation_max_calls, msg)
+    end
+
+    def check_duplicate(fn_name = nil, args = [], kwargs = {})
+      signature = create_signature(fn_name, args, kwargs)
+
+      if @call_signatures.include?(signature)
+        msg = "GardeFou: duplicate call detected for #{fn_name} with args #{args.inspect} and kwargs #{kwargs.inspect}"
+        handle_violation(@on_violation_duplicate_call, msg)
+      else
+        @call_signatures.add(signature)
+      end
+    end
+
+    def create_signature(fn_name, args, kwargs)
+      # Create a deterministic signature for duplicate detection
+      sorted_kwargs = kwargs.sort.to_h
+      {
+        fn_name: fn_name,
+        args: args,
+        kwargs: sorted_kwargs
+      }.to_json
+    end
+
+    def handle_violation(handler, message)
+      case handler
+      when 'warn'
+        warn(message)
+      when 'raise'
+        raise QuotaExceededError, message
+      when Proc
+        handler.call(self)
+      else
+        raise ArgumentError, "Invalid violation handler: #{handler}"
+      end
+    end
+  end
+end

data/lib/gardefou/storage.rb

@@ -0,0 +1,58 @@
+require 'json'
+require 'set'
+
+module Gardefou
+  # Utility class for creating call signatures for duplicate detection
+  class CallSignature
+    attr_reader :fn_name, :args, :kwargs
+
+    def initialize(fn_name, args, kwargs)
+      @fn_name = fn_name
+      @args = args
+      @kwargs = kwargs
+    end
+
+    def to_s
+      # Create deterministic string representation
+      sorted_kwargs = @kwargs.sort.to_h
+      {
+        fn_name: @fn_name,
+        args: @args,
+        kwargs: sorted_kwargs
+      }.to_json
+    end
+
+    def ==(other)
+      other.is_a?(CallSignature) && to_s == other.to_s
+    end
+
+    def hash
+      to_s.hash
+    end
+
+    alias eql? ==
+  end
+
+  # Storage adapter for tracking calls (future extension point)
+  class StorageAdapter
+    def initialize
+      @signatures = Set.new
+    end
+
+    def store_signature(signature)
+      @signatures.add(signature)
+    end
+
+    def signature_exists?(signature)
+      @signatures.include?(signature)
+    end
+
+    def clear
+      @signatures.clear
+    end
+
+    def count
+      @signatures.size
+    end
+  end
+end

data/lib/gardefou/version.rb

@@ -0,0 +1,3 @@
+module Gardefou
+  VERSION = '0.1.0'
+end

data/lib/gardefou/wrapper.rb

@@ -0,0 +1,34 @@
+require_relative 'garde_fou'
+
+module Gardefou
+  # Mixin module to add garde-fou protection to any class
+  module GuardedClient
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # Class-level method to set up protection for specific methods
+      def guard_method(method_name, **options)
+        original_method = instance_method(method_name)
+        guard = GardeFou.new(**options)
+
+        define_method(method_name) do |*args, **kwargs, &block|
+          guard.call(original_method.bind(self), *args, **kwargs, &block)
+        end
+      end
+
+      # Protect all methods matching a pattern
+      def guard_methods(pattern, **options)
+        instance_methods.grep(pattern).each do |method_name|
+          guard_method(method_name, **options)
+        end
+      end
+    end
+
+    # Instance-level guard creation
+    def create_guard(**options)
+      GardeFou.new(**options)
+    end
+  end
+end

data/lib/gardefou.rb

@@ -0,0 +1,18 @@
+# Main garde-fou library
+require_relative 'gardefou/version'
+require_relative 'gardefou/profile'
+require_relative 'gardefou/garde_fou'
+require_relative 'gardefou/storage'
+require_relative 'gardefou/wrapper'
+
+module Gardefou
+  # Convenience method to create a new guard
+  def self.new(**options)
+    GardeFou.new(**options)
+  end
+
+  # Create a guard with a profile
+  def self.with_profile(profile)
+    GardeFou.new(profile: profile)
+  end
+end

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification
+name: garde_fou
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Robin Fiévet
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2025-08-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: A lightweight guard for protecting against accidental over-usage of paid
+  API calls. Provides call counting and duplicate detection to help you avoid unexpected
+  API bills.
+email:
+- robinfievet@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- lib/gardefou.rb
+- lib/gardefou/garde_fou.rb
+- lib/gardefou/profile.rb
+- lib/gardefou/storage.rb
+- lib/gardefou/version.rb
+- lib/gardefou/wrapper.rb
+homepage: https://github.com/rfievet/garde-fou
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/rfievet/garde-fou
+  source_code_uri: https://github.com/rfievet/garde-fou
+  changelog_uri: https://github.com/rfievet/garde-fou/blob/main/ruby/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Protective wrappers around paid API clients with quotas & duplicate detection
+test_files: []