spyglasses 1.0.0

data/lib/spyglasses/middleware.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module Spyglasses
+  class Middleware
+    include Spyglasses::Types
+
+    def initialize(app, options = {})
+      @app = app
+      @configuration = setup_configuration(options)
+      @client = Client.new(@configuration)
+      @exclude_paths = @configuration.exclude_paths + default_exclude_paths
+      
+      log_debug("Spyglasses middleware initialized with configuration: #{@configuration.to_h}")
+    end
+
+    def call(env)
+      request_start_time = Time.now
+      request = Rack::Request.new(env)
+      
+      # Skip excluded paths
+      if should_exclude_path?(request.path)
+        log_debug("Excluding path: #{request.path}")
+        return @app.call(env)
+      end
+
+      # Extract request information
+      user_agent = request.user_agent || ''
+      referrer = request.referrer || ''
+      
+      log_debug("Processing request to #{request.path}")
+      log_debug("User-Agent: #{user_agent[0..99]}#{user_agent.length > 100 ? '...' : ''}")
+      log_debug("Referrer: #{referrer}") unless referrer.empty?
+
+      # Detect bot or AI referrer
+      detection_result = @client.detect(user_agent, referrer)
+      
+      if detection_result.source_type != 'none'
+        log_debug("Detection result: #{detection_result.to_h}")
+        
+        # Handle blocking
+        if detection_result.should_block
+          log_debug("Blocking request from #{detection_result.source_type}: #{detection_result.matched_pattern}")
+          
+          # Log the blocked request
+          log_request_async(detection_result, request, 403, Time.now - request_start_time)
+          
+          # Return 403 Forbidden
+          return forbidden_response
+        end
+      end
+
+      # Process the request normally
+      begin
+        status, headers, response = @app.call(env)
+        response_time = Time.now - request_start_time
+        
+        # Log successful requests with detection results
+        if detection_result.source_type != 'none'
+          log_request_async(detection_result, request, status, response_time)
+        end
+        
+        [status, headers, response]
+      rescue => e
+        # Log error requests if we detected something
+        if detection_result.source_type != 'none'
+          response_time = Time.now - request_start_time
+          log_request_async(detection_result, request, 500, response_time)
+        end
+        
+        raise e
+      end
+    end
+
+    private
+
+    def setup_configuration(options)
+      config = Configuration.new
+      
+      # Override with provided options
+      options.each do |key, value|
+        case key.to_sym
+        when :api_key
+          config.api_key = value
+        when :debug
+          config.debug = value
+        when :collect_endpoint
+          config.collect_endpoint = value
+        when :patterns_endpoint
+          config.patterns_endpoint = value
+        when :auto_sync
+          config.auto_sync = value
+        when :platform_type
+          config.platform_type = value
+        when :cache_ttl
+          config.cache_ttl = value.to_i
+        when :exclude_paths
+          config.exclude_paths = Array(value)
+        end
+      end
+      
+      config
+    end
+
+    def default_exclude_paths
+      [
+        # Static assets
+        /\.(css|js|png|jpg|jpeg|gif|svg|ico|woff|woff2|ttf|eot)$/i,
+        # Rails specific
+        %r{^/rails/},
+        %r{^/assets/},
+        # Common paths
+        %r{^/favicon\.ico},
+        %r{^/robots\.txt},
+        %r{^/sitemap\.xml},
+        # Health checks
+        %r{^/health},
+        %r{^/status},
+        %r{^/ping}
+      ]
+    end
+
+    def should_exclude_path?(path)
+      @exclude_paths.any? do |pattern|
+        case pattern
+        when String
+          path.include?(pattern)
+        when Regexp
+          pattern.match?(path)
+        else
+          false
+        end
+      end
+    end
+
+    def log_request_async(detection_result, request, status, response_time)
+      return unless @configuration.api_key_present?
+
+      request_info = {
+        url: request.url,
+        user_agent: request.user_agent || '',
+        ip_address: extract_client_ip(request),
+        request_method: request.request_method,
+        request_path: request.path,
+        request_query: request.query_string.empty? ? nil : request.query_string,
+        referrer: request.referrer,
+        response_status: status,
+        response_time_ms: (response_time * 1000).round,
+        headers: extract_headers(request)
+      }
+
+      @client.log_request(detection_result, request_info)
+      
+      log_debug("Logging #{detection_result.source_type} visit: #{detection_result.matched_pattern}")
+    end
+
+    def extract_client_ip(request)
+      # Try various headers to get the real client IP
+      [
+        request.env['HTTP_X_FORWARDED_FOR'],
+        request.env['HTTP_X_REAL_IP'],
+        request.env['HTTP_CF_CONNECTING_IP'], # Cloudflare
+        request.env['HTTP_X_CLIENT_IP'],
+        request.env['REMOTE_ADDR']
+      ].find { |ip| ip && !ip.empty? && ip != '127.0.0.1' } || request.ip
+    end
+
+    def extract_headers(request)
+      headers = {}
+      request.env.each do |key, value|
+        if key.start_with?('HTTP_') && value.is_a?(String)
+          header_name = key[5..-1].downcase.tr('_', '-')
+          headers[header_name] = value
+        end
+      end
+      headers
+    end
+
+    def forbidden_response
+      [
+        403,
+        {
+          'Content-Type' => 'text/plain',
+          'Content-Length' => '13'
+        },
+        ['Access Denied']
+      ]
+    end
+
+    def log_debug(message)
+      return unless @configuration.debug?
+      
+      puts "[Spyglasses] #{message}"
+    end
+  end
+end 

data/lib/spyglasses/types.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+module Spyglasses
+  module Types
+    # Base detection result
+    class DetectionResult
+      attr_accessor :is_bot, :should_block, :source_type, :matched_pattern, :info
+
+      def initialize(is_bot: false, should_block: false, source_type: 'none', matched_pattern: nil, info: nil)
+        @is_bot = is_bot
+        @should_block = should_block
+        @source_type = source_type
+        @matched_pattern = matched_pattern
+        @info = info
+      end
+
+      def to_h
+        {
+          is_bot: @is_bot,
+          should_block: @should_block,
+          source_type: @source_type,
+          matched_pattern: @matched_pattern,
+          info: @info&.to_h
+        }
+      end
+    end
+
+    # Bot pattern from API
+    class BotPattern
+      attr_accessor :pattern, :url, :type, :category, :subcategory, :company, 
+                    :is_compliant, :is_ai_model_trainer, :intent, :instances
+
+      def initialize(data = {})
+        @pattern = data['pattern'] || data[:pattern]
+        @url = data['url'] || data[:url]
+        @type = data['type'] || data[:type]
+        @category = data['category'] || data[:category]
+        @subcategory = data['subcategory'] || data[:subcategory]
+        @company = data['company'] || data[:company]
+        @is_compliant = data['is_compliant'] || data[:is_compliant] || data['isCompliant']
+        @is_ai_model_trainer = data['is_ai_model_trainer'] || data[:is_ai_model_trainer] || data['isAiModelTrainer']
+        @intent = data['intent'] || data[:intent]
+        @instances = data['instances'] || data[:instances] || []
+      end
+
+      def to_h
+        {
+          pattern: @pattern,
+          url: @url,
+          type: @type,
+          category: @category,
+          subcategory: @subcategory,
+          company: @company,
+          is_compliant: @is_compliant,
+          is_ai_model_trainer: @is_ai_model_trainer,
+          intent: @intent,
+          instances: @instances
+        }
+      end
+    end
+
+    # Bot info for detection results
+    class BotInfo
+      attr_accessor :pattern, :type, :category, :subcategory, :company, 
+                    :is_compliant, :is_ai_model_trainer, :intent, :url
+
+      def initialize(data = {})
+        @pattern = data['pattern'] || data[:pattern]
+        @type = data['type'] || data[:type]
+        @category = data['category'] || data[:category]
+        @subcategory = data['subcategory'] || data[:subcategory]
+        @company = data['company'] || data[:company]
+        @is_compliant = data['is_compliant'] || data[:is_compliant] || false
+        @is_ai_model_trainer = data['is_ai_model_trainer'] || data[:is_ai_model_trainer] || false
+        @intent = data['intent'] || data[:intent]
+        @url = data['url'] || data[:url]
+      end
+
+      def to_h
+        {
+          pattern: @pattern,
+          type: @type,
+          category: @category,
+          subcategory: @subcategory,
+          company: @company,
+          is_compliant: @is_compliant,
+          is_ai_model_trainer: @is_ai_model_trainer,
+          intent: @intent,
+          url: @url
+        }
+      end
+    end
+
+    # AI referrer info
+    class AiReferrerInfo
+      attr_accessor :id, :name, :company, :url, :patterns, :description, :logo_url
+
+      def initialize(data = {})
+        @id = data['id'] || data[:id]
+        @name = data['name'] || data[:name]
+        @company = data['company'] || data[:company]
+        @url = data['url'] || data[:url]
+        @patterns = data['patterns'] || data[:patterns] || []
+        @description = data['description'] || data[:description]
+        @logo_url = data['logo_url'] || data[:logo_url] || data['logoUrl']
+      end
+
+      def to_h
+        {
+          id: @id,
+          name: @name,
+          company: @company,
+          url: @url,
+          patterns: @patterns,
+          description: @description,
+          logo_url: @logo_url
+        }
+      end
+    end
+
+    # API pattern response
+    class ApiPatternResponse
+      attr_accessor :version, :patterns, :ai_referrers, :property_settings
+
+      def initialize(data = {})
+        @version = data['version'] || data[:version]
+        @patterns = (data['patterns'] || data[:patterns] || []).map { |p| BotPattern.new(p) }
+        @ai_referrers = (data['ai_referrers'] || data[:ai_referrers] || data['aiReferrers'] || []).map { |r| AiReferrerInfo.new(r) }
+        
+        settings_data = data['property_settings'] || data[:property_settings] || data['propertySettings'] || {}
+        @property_settings = PropertySettings.new(settings_data)
+      end
+
+      def to_h
+        {
+          version: @version,
+          patterns: @patterns.map(&:to_h),
+          ai_referrers: @ai_referrers.map(&:to_h),
+          property_settings: @property_settings.to_h
+        }
+      end
+    end
+
+    # Property settings from API
+    class PropertySettings
+      attr_accessor :block_ai_model_trainers, :custom_blocks, :custom_allows
+
+      def initialize(data = {})
+        @block_ai_model_trainers = data['block_ai_model_trainers'] || data[:block_ai_model_trainers] || data['blockAiModelTrainers'] || false
+        @custom_blocks = data['custom_blocks'] || data[:custom_blocks] || data['customBlocks'] || []
+        @custom_allows = data['custom_allows'] || data[:custom_allows] || data['customAllows'] || []
+      end
+
+      def to_h
+        {
+          block_ai_model_trainers: @block_ai_model_trainers,
+          custom_blocks: @custom_blocks,
+          custom_allows: @custom_allows
+        }
+      end
+    end
+
+    # Collector payload
+    class CollectorPayload
+      attr_accessor :url, :user_agent, :ip_address, :request_method, :request_path, 
+                    :request_query, :request_body, :referrer, :response_status, 
+                    :response_time_ms, :headers, :timestamp, :platform_type, :metadata
+
+      def initialize(data = {})
+        @url = data[:url]
+        @user_agent = data[:user_agent]
+        @ip_address = data[:ip_address]
+        @request_method = data[:request_method]
+        @request_path = data[:request_path]
+        @request_query = data[:request_query]
+        @request_body = data[:request_body]
+        @referrer = data[:referrer]
+        @response_status = data[:response_status]
+        @response_time_ms = data[:response_time_ms]
+        @headers = data[:headers] || {}
+        @timestamp = data[:timestamp] || Time.now.utc.iso8601
+        @platform_type = data[:platform_type]
+        @metadata = data[:metadata] || {}
+      end
+
+      def to_h
+        {
+          url: @url,
+          user_agent: @user_agent,
+          ip_address: @ip_address,
+          request_method: @request_method,
+          request_path: @request_path,
+          request_query: @request_query,
+          request_body: @request_body,
+          referrer: @referrer,
+          response_status: @response_status,
+          response_time_ms: @response_time_ms,
+          headers: @headers,
+          timestamp: @timestamp,
+          platform_type: @platform_type,
+          metadata: @metadata
+        }
+      end
+
+      def to_json(*args)
+        to_h.to_json(*args)
+      end
+    end
+  end
+end 

data/lib/spyglasses/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Spyglasses
+  VERSION = '1.0.0'
+end 

data/lib/spyglasses.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'spyglasses/version'
+require_relative 'spyglasses/types'
+require_relative 'spyglasses/configuration'
+require_relative 'spyglasses/client'
+require_relative 'spyglasses/middleware'
+
+module Spyglasses
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class ApiError < Error; end
+
+  class << self
+    # Global configuration
+    def configure
+      yield(configuration)
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def reset_configuration!
+      @configuration = nil
+    end
+  end
+end 

metadata

@@ -0,0 +1,203 @@
+--- !ruby/object:Gem::Specification
+name: spyglasses
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Orchestra AI, Inc.
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-06-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  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: 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: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  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: webmock
+  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: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.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'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: Spyglasses provides comprehensive AI agent detection and management capabilities
+  for Ruby web applications, including Rails, Sinatra, and other Rack-based frameworks.
+email:
+- support@spyglasses.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rspec_status"
+- CHANGELOG.md
+- DEVELOPMENT.md
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- Rakefile
+- lib/spyglasses.rb
+- lib/spyglasses/client.rb
+- lib/spyglasses/configuration.rb
+- lib/spyglasses/middleware.rb
+- lib/spyglasses/types.rb
+- lib/spyglasses/version.rb
+homepage: https://www.spyglasses.io
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://www.spyglasses.io
+  source_code_uri: https://github.com/spyglasses/spyglasses-ruby
+  documentation_uri: https://docs.spyglasses.io/ruby
+  changelog_uri: https://github.com/spyglasses/spyglasses-ruby/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.3
+signing_key:
+specification_version: 4
+summary: AI Agent Detection and Management for Ruby web applications
+test_files: []