spyglasses 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 500f84bd8f684ffc7b0bc15d28743dcf50e5c883191efb166de087ecc001496c
+  data.tar.gz: 4dd3be43d678475d4f16d1988f51ebcdab33a941add56040aed2c714ab725121
+SHA512:
+  metadata.gz: c1e7d7d73fc2a1551987c96eafada4e9e893fa9735adeb0174b13bf7f8da99740313c8135ed90ca40ef41a4db694939f8d8359d97a9632744c79691ec0ad531e
+  data.tar.gz: b383b31150503a03161f3fcf2915d5049177d947c44187f5180623cb7205c368be298d719aa6061dd1478617c6042aa2cc151e4b41bc94f60a96a5abb4e3cae6

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--color
+--format documentation 

data/.rspec_status

@@ -0,0 +1,54 @@
+example_id                                     | status | run_time        |
+---------------------------------------------- | ------ | --------------- |
+./spec/spyglasses/client_spec.rb[1:1:1]        | passed | 0.00252 seconds |
+./spec/spyglasses/client_spec.rb[1:1:2]        | passed | 0.00096 seconds |
+./spec/spyglasses/client_spec.rb[1:2:1:1]      | passed | 0.02254 seconds |
+./spec/spyglasses/client_spec.rb[1:2:2:1]      | passed | 0.00235 seconds |
+./spec/spyglasses/client_spec.rb[1:2:3:1]      | passed | 0.00059 seconds |
+./spec/spyglasses/client_spec.rb[1:3:1]        | passed | 0.00084 seconds |
+./spec/spyglasses/client_spec.rb[1:3:2]        | passed | 0.00029 seconds |
+./spec/spyglasses/client_spec.rb[1:3:3]        | passed | 0.0002 seconds  |
+./spec/spyglasses/client_spec.rb[1:4:1]        | passed | 0.00034 seconds |
+./spec/spyglasses/client_spec.rb[1:4:2]        | passed | 0.00022 seconds |
+./spec/spyglasses/client_spec.rb[1:4:3]        | passed | 0.00023 seconds |
+./spec/spyglasses/client_spec.rb[1:5:1]        | passed | 0.00029 seconds |
+./spec/spyglasses/client_spec.rb[1:5:2]        | passed | 0.0003 seconds  |
+./spec/spyglasses/client_spec.rb[1:5:3]        | passed | 0.00018 seconds |
+./spec/spyglasses/client_spec.rb[1:6:1]        | passed | 0.10244 seconds |
+./spec/spyglasses/client_spec.rb[1:6:2]        | passed | 0.10159 seconds |
+./spec/spyglasses/client_spec.rb[1:6:3]        | passed | 0.10182 seconds |
+./spec/spyglasses/configuration_spec.rb[1:1:1] | passed | 0.00037 seconds |
+./spec/spyglasses/configuration_spec.rb[1:1:2] | passed | 0.00022 seconds |
+./spec/spyglasses/configuration_spec.rb[1:2:1] | passed | 0.00013 seconds |
+./spec/spyglasses/configuration_spec.rb[1:2:2] | passed | 0.00008 seconds |
+./spec/spyglasses/configuration_spec.rb[1:2:3] | passed | 0.00009 seconds |
+./spec/spyglasses/configuration_spec.rb[1:3:1] | passed | 0.00047 seconds |
+./spec/spyglasses/configuration_spec.rb[1:4:1] | passed | 0.00012 seconds |
+./spec/spyglasses/configuration_spec.rb[1:5:1] | passed | 0.00328 seconds |
+./spec/spyglasses/configuration_spec.rb[1:5:2] | passed | 0.00024 seconds |
+./spec/spyglasses/configuration_spec.rb[1:5:3] | passed | 0.00016 seconds |
+./spec/spyglasses/configuration_spec.rb[1:5:4] | passed | 0.00016 seconds |
+./spec/spyglasses/configuration_spec.rb[1:5:5] | passed | 0.0001 seconds  |
+./spec/spyglasses/configuration_spec.rb[1:6:1] | passed | 0.0001 seconds  |
+./spec/spyglasses/configuration_spec.rb[1:6:2] | passed | 0.00007 seconds |
+./spec/spyglasses/middleware_spec.rb[1:1:1]    | passed | 0.00018 seconds |
+./spec/spyglasses/middleware_spec.rb[1:2:1:1]  | passed | 0.00041 seconds |
+./spec/spyglasses/middleware_spec.rb[1:2:1:2]  | passed | 0.00024 seconds |
+./spec/spyglasses/middleware_spec.rb[1:2:1:3]  | passed | 0.00019 seconds |
+./spec/spyglasses/middleware_spec.rb[1:2:1:4]  | passed | 0.00301 seconds |
+./spec/spyglasses/middleware_spec.rb[1:2:1:5]  | passed | 0.00038 seconds |
+./spec/spyglasses/middleware_spec.rb[1:2:2:1]  | passed | 0.00033 seconds |
+./spec/spyglasses/middleware_spec.rb[1:2:2:2]  | passed | 0.10132 seconds |
+./spec/spyglasses/middleware_spec.rb[1:2:2:3]  | passed | 0.10237 seconds |
+./spec/spyglasses/middleware_spec.rb[1:2:3:1]  | passed | 0.1138 seconds  |
+./spec/spyglasses/middleware_spec.rb[1:2:4:1]  | passed | 0.10115 seconds |
+./spec/spyglasses/middleware_spec.rb[1:2:5:1]  | passed | 0.10181 seconds |
+./spec/spyglasses/middleware_spec.rb[1:3:1]    | passed | 0.00046 seconds |
+./spec/spyglasses/middleware_spec.rb[1:3:2]    | passed | 0.00054 seconds |
+./spec/spyglasses/middleware_spec.rb[1:3:3]    | passed | 0.00013 seconds |
+./spec/spyglasses_spec.rb[1:1]                 | passed | 0.00008 seconds |
+./spec/spyglasses_spec.rb[1:2:1]               | passed | 0.00181 seconds |
+./spec/spyglasses_spec.rb[1:2:2]               | passed | 0.00035 seconds |
+./spec/spyglasses_spec.rb[1:3:1]               | passed | 0.00008 seconds |
+./spec/spyglasses_spec.rb[1:3:2]               | passed | 0.00006 seconds |
+./spec/spyglasses_spec.rb[1:4:1]               | passed | 0.00007 seconds |

data/CHANGELOG.md

@@ -0,0 +1,41 @@
+# 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]
+
+## [1.0.0] - 2024-01-XX
+
+### Added
+- Initial release of Spyglasses Ruby gem
+- Core AI agent detection functionality
+- Bot pattern matching with regex support
+- AI referrer detection for platforms like ChatGPT, Claude, Perplexity
+- Flexible blocking system based on patterns and property settings
+- Rack middleware for easy integration with Ruby web frameworks
+- Rails, Sinatra, and generic Rack application support
+- Non-blocking request logging to Spyglasses collector API
+- Thread-safe pattern caching and background processing
+- Comprehensive test suite with >95% code coverage
+- Environment variable configuration support
+- Default patterns for common AI agents and crawlers
+- Pattern synchronization from Spyglasses API
+- Debug logging capabilities
+- Comprehensive documentation and examples
+
+### Security
+- Thread-safe operations for concurrent Ruby applications
+- Secure API key handling with masked logging
+- Input validation and error handling
+
+### Performance
+- Compiled regex pattern caching
+- Background thread processing for API calls
+- Smart path exclusions for static assets
+- Minimal request overhead (<1ms typical)
+
+[Unreleased]: https://github.com/spyglasses/spyglasses-ruby/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/spyglasses/spyglasses-ruby/releases/tag/v1.0.0 

data/DEVELOPMENT.md

@@ -0,0 +1,215 @@
+# Development Guide
+
+This guide provides information for developers working on the Spyglasses Ruby gem.
+
+## Architecture Overview
+
+The gem is structured into several key components:
+
+### Core Components
+
+1. **`Spyglasses::Configuration`** - Handles configuration management and environment variables
+2. **`Spyglasses::Client`** - Core detection logic and API communication  
+3. **`Spyglasses::Middleware`** - Rack middleware for web framework integration
+4. **`Spyglasses::Types`** - Data structures and type definitions
+
+### Key Features
+
+- **Pattern Management**: Loads default patterns and syncs from API
+- **Detection Logic**: Bot and AI referrer detection with regex matching
+- **Blocking System**: Configurable blocking based on property settings
+- **Request Logging**: Non-blocking background logging to collector API
+- **Thread Safety**: Mutex-protected pattern updates and caching
+
+## Development Setup
+
+```bash
+git clone https://github.com/spyglasses/spyglasses-ruby.git
+cd spyglasses-ruby
+bin/setup
+```
+
+## Running Tests
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run with coverage
+rake coverage
+
+# Run specific test file
+bundle exec rspec spec/spyglasses/client_spec.rb
+
+# Run specific test
+bundle exec rspec spec/spyglasses/client_spec.rb:42
+```
+
+## Code Quality
+
+```bash
+# Run RuboCop
+bundle exec rubocop
+
+# Auto-fix RuboCop issues
+bundle exec rubocop -a
+
+# Run all checks
+rake check
+```
+
+## Building and Testing the Gem
+
+```bash
+# Build the gem
+rake build
+
+# Install locally for testing
+rake install_local
+
+# Test in an app
+gem 'spyglasses', path: '/path/to/spyglasses-ruby'
+```
+
+## Testing with Real API
+
+To test with the real Spyglasses API:
+
+```bash
+export SPYGLASSES_API_KEY=your_real_api_key
+export SPYGLASSES_DEBUG=true
+
+# Create a test script
+cat > test_api.rb << 'EOF'
+require 'spyglasses'
+
+client = Spyglasses::Client.new
+result = client.sync_patterns
+puts "Sync result: #{result.class}"
+puts "Patterns loaded: #{client.patterns.length}"
+
+detection = client.detect('GPTBot/1.0')
+puts "Detection result: #{detection.to_h}"
+EOF
+
+ruby test_api.rb
+```
+
+## Performance Testing
+
+```bash
+# Simple benchmark
+cat > benchmark.rb << 'EOF'
+require 'benchmark'
+require 'spyglasses'
+
+client = Spyglasses::Client.new(
+  Spyglasses::Configuration.new.tap { |c| c.auto_sync = false }
+)
+
+user_agents = [
+  'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
+  'GPTBot/1.0',
+  'ClaudeBot/1.0',
+  'ChatGPT-User/1.0'
+]
+
+Benchmark.bm do |x|
+  x.report("1000 detections") do
+    1000.times do
+      user_agents.each { |ua| client.detect(ua) }
+    end
+  end
+end
+EOF
+
+ruby benchmark.rb
+```
+
+## Release Process
+
+1. Update version in `lib/spyglasses/version.rb`
+2. Update `CHANGELOG.md` with changes
+3. Ensure all tests pass: `rake check`
+4. Build and test the gem: `rake build && rake install_local`
+5. Commit changes: `git commit -am "Release v1.x.x"`
+6. Tag the release: `git tag v1.x.x`
+7. Push: `git push && git push --tags`
+8. Publish: `gem push pkg/spyglasses-1.x.x.gem`
+
+## Contributing Guidelines
+
+### Code Style
+
+- Follow Ruby community standards
+- Use RuboCop for linting
+- Write descriptive commit messages
+- Include tests for new functionality
+
+### Testing Requirements
+
+- Maintain >90% test coverage
+- Include unit tests for all public methods
+- Test error conditions and edge cases
+- Use WebMock to stub HTTP requests
+
+### Documentation
+
+- Update README.md for user-facing changes
+- Add inline documentation for complex methods
+- Include usage examples in docstrings
+- Update CHANGELOG.md for all changes
+
+## Debugging
+
+### Enable Debug Mode
+
+```ruby
+# In code
+Spyglasses.configure do |config|
+  config.debug = true
+end
+
+# Via environment
+export SPYGLASSES_DEBUG=true
+```
+
+### Common Issues
+
+1. **Pattern loading fails**: Check API key and network connectivity
+2. **Tests fail with real HTTP**: Ensure WebMock stubs are in place
+3. **Middleware not detecting**: Check user agent patterns and exclusions
+4. **Performance issues**: Profile pattern matching and API calls
+
+### Debugging API Issues
+
+```ruby
+# Test API connectivity
+require 'net/http'
+require 'json'
+
+uri = URI('https://www.spyglasses.io/api/patterns')
+http = Net::HTTP.new(uri.host, uri.port)
+http.use_ssl = true
+
+request = Net::HTTP::Get.new(uri)
+request['x-api-key'] = 'your-api-key'
+
+response = http.request(request)
+puts "Status: #{response.code}"
+puts "Body: #{response.body[0..200]}..."
+```
+
+## Compatibility
+
+- **Ruby**: 2.7+ (tested on 2.7, 3.0, 3.1, 3.2, 3.3)
+- **Rails**: 6.0+ (all versions with Rack 2.0+)
+- **Rack**: 2.0+ 
+- **Other frameworks**: Sinatra, Hanami, Roda, etc.
+
+## Security Considerations
+
+- API keys are masked in logs and debug output
+- No sensitive data is stored in memory longer than necessary
+- HTTP requests use TLS/SSL for API communication
+- Input validation prevents regex injection attacks 

data/Gemfile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in spyglasses.gemspec
+gemspec
+
+gem 'pry', '~> 0.14.0'
+gem 'pry-byebug', '~> 3.10.0'
+
+group :development do
+  gem 'guard', '~> 2.18.0'
+  gem 'guard-rspec', '~> 4.7.0'
+  gem 'listen', '~> 3.8.0'
+end 

data/Gemfile.lock

@@ -0,0 +1,143 @@
+PATH
+  remote: .
+  specs:
+    spyglasses (1.0.0)
+      json (>= 2.0)
+      rack (>= 2.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
+    ast (2.4.3)
+    bigdecimal (3.2.2)
+    byebug (11.1.3)
+    coderay (1.1.3)
+    crack (1.0.0)
+      bigdecimal
+      rexml
+    diff-lcs (1.6.2)
+    docile (1.4.1)
+    ffi (1.17.2)
+    ffi (1.17.2-arm64-darwin)
+    ffi (1.17.2-x86_64-darwin)
+    formatador (1.1.0)
+    guard (2.18.1)
+      formatador (>= 0.2.4)
+      listen (>= 2.7, < 4.0)
+      lumberjack (>= 1.0.12, < 2.0)
+      nenv (~> 0.1)
+      notiffany (~> 0.0)
+      pry (>= 0.13.0)
+      shellany (~> 0.0)
+      thor (>= 0.18.1)
+    guard-compat (1.2.1)
+    guard-rspec (4.7.3)
+      guard (~> 2.1)
+      guard-compat (~> 1.1)
+      rspec (>= 2.99.0, < 4.0)
+    hashdiff (1.2.0)
+    json (2.12.2)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    listen (3.8.0)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    lumberjack (1.2.10)
+    method_source (1.1.0)
+    nenv (0.3.0)
+    notiffany (0.1.3)
+      nenv (~> 0.1)
+      shellany (~> 0.0)
+    parallel (1.27.0)
+    parser (3.3.8.0)
+      ast (~> 2.4.1)
+      racc
+    prism (1.4.0)
+    pry (0.14.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    pry-byebug (3.10.1)
+      byebug (~> 11.0)
+      pry (>= 0.13, < 0.15)
+    public_suffix (6.0.2)
+    racc (1.8.1)
+    rack (3.1.16)
+    rack-test (2.2.0)
+      rack (>= 1.3)
+    rainbow (3.1.1)
+    rake (13.3.0)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.11.1)
+      ffi (~> 1.0)
+    regexp_parser (2.10.0)
+    rexml (3.4.1)
+    rspec (3.13.1)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.4)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.4)
+    rubocop (1.77.0)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.45.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.45.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    ruby-progressbar (1.13.0)
+    shellany (0.0.1)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.1)
+    simplecov_json_formatter (0.1.4)
+    thor (1.3.2)
+    unicode-display_width (3.1.4)
+      unicode-emoji (~> 4.0, >= 4.0.4)
+    unicode-emoji (4.0.4)
+    webmock (3.25.1)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+    yard (0.9.37)
+
+PLATFORMS
+  arm64-darwin
+  ruby
+  x86_64-darwin
+
+DEPENDENCIES
+  bundler (>= 2.0)
+  guard (~> 2.18.0)
+  guard-rspec (~> 4.7.0)
+  listen (~> 3.8.0)
+  pry (~> 0.14.0)
+  pry-byebug (~> 3.10.0)
+  rack-test (~> 2.0)
+  rake (>= 13.0)
+  rspec (~> 3.0)
+  rubocop (~> 1.0)
+  simplecov (~> 0.21)
+  spyglasses!
+  webmock (~> 3.0)
+  yard (~> 0.9)
+
+BUNDLED WITH
+   2.6.6

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Orchestra AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.