# Ruby Integration

> Add the spyglasses gem to track AI bots and AI referral traffic in Rails, Sinatra or any Rack app. Covers installation, middleware and configuration.

Spyglasses integrates seamlessly with Ruby web applications through our official gem. The gem provides a Rack middleware that works with Rails, Sinatra, and any other Rack-based Ruby framework.

## Installation

1. **Add the gem to your Gemfile**:
   ```ruby
   gem 'spyglasses'
   ```

   Then run:
   ```bash
   bundle install
   ```

   Or install directly:
   ```bash
   gem install spyglasses
   ```

2. **Set your API key**:
   Add your Spyglasses API key to your environment variables:
   ```env
   SPYGLASSES_API_KEY=your_api_key_here
   ```

## Rails Integration

### Option 1: Application Configuration (Recommended)

Add the middleware to your Rails application in `config/application.rb`:

```ruby
# config/application.rb
class Application < Rails::Application
  # Add Spyglasses middleware
  config.middleware.use Spyglasses::Middleware
end
```

### Option 2: Initializer with Configuration

Create an initializer for more control over the configuration:

```ruby
# config/initializers/spyglasses.rb
Spyglasses.configure do |config|
  config.api_key = ENV['SPYGLASSES_API_KEY']
  config.debug = Rails.env.development?
  config.platform_type = 'rails'
  config.exclude_paths = [
    '/rails/active_storage',  # Exclude Active Storage routes
    '/admin',                 # Exclude admin routes
    %r{^/api/internal}        # Exclude internal API routes (regex)
  ]
end

# Add middleware with configuration
Rails.application.config.middleware.use Spyglasses::Middleware
```

### Rails-Specific Considerations

**Active Storage**: By default, Rails Active Storage routes (`/rails/active_storage/*`) are automatically excluded from monitoring.

**Asset Pipeline**: Static assets are automatically excluded, but if you have custom asset routes, add them to `exclude_paths`.

**API-Only Applications**: For Rails API applications, the middleware works the same way:

```ruby
# config/application.rb
class Application < Rails::Application
  config.api_only = true
  config.middleware.use Spyglasses::Middleware
end
```

**Development vs Production**: Consider enabling debug mode only in development:

```ruby
# config/initializers/spyglasses.rb
Spyglasses.configure do |config|
  config.debug = Rails.env.development?
  config.exclude_paths = Rails.env.development? ? ['/debug'] : []
end
```

## Sinatra Integration

For Sinatra applications, add the middleware using the `use` directive:

```ruby
# app.rb
require 'sinatra'
require 'spyglasses'

# Configure Spyglasses
configure do
  Spyglasses.configure do |config|
    config.api_key = ENV['SPYGLASSES_API_KEY']
    config.platform_type = 'sinatra'
    config.debug = development?
  end
end

# Add middleware
use Spyglasses::Middleware

get '/' do
  'Hello World!'
end
```

### Sinatra with Options

You can also pass options directly to the middleware:

```ruby
use Spyglasses::Middleware, {
  api_key: ENV['SPYGLASSES_API_KEY'],
  debug: development?,
  exclude_paths: ['/health', '/metrics']
}
```

## Other Ruby Frameworks

### Hanami

```ruby
# config/environment.rb
Hanami.configure do
  middleware.use Spyglasses::Middleware, api_key: ENV['SPYGLASSES_API_KEY']
end
```

### Roda

```ruby
# app.rb
require 'roda'
require 'spyglasses'

class App < Roda
  use Spyglasses::Middleware, api_key: ENV['SPYGLASSES_API_KEY']
  
  route do |r|
    r.root do
      'Hello World!'
    end
  end
end
```

### Rack Application

For pure Rack applications:

```ruby
# config.ru
require 'spyglasses'

use Spyglasses::Middleware, api_key: ENV['SPYGLASSES_API_KEY']

app = lambda do |env|
  [200, {'Content-Type' => 'text/plain'}, ['Hello World!']]
end

run app
```

## Configuration Options

The middleware accepts these configuration options:

```ruby
use Spyglasses::Middleware, {
  api_key: ENV['SPYGLASSES_API_KEY'],     # Required: Your API key
  debug: false,                           # Enable debug logging
  auto_sync: true,                        # Auto-sync patterns on startup
  platform_type: 'rails',                # Platform identifier
  exclude_paths: [                        # Paths to exclude
    '/admin',                             # String matching
    %r{^/api/internal},                   # Regex patterns
    '/health'
  ],
  collect_endpoint: 'https://...',        # Custom collector endpoint
  patterns_endpoint: 'https://...'        # Custom patterns endpoint
}
```

## Environment Variables

Set these environment variables for configuration:

| Variable | Description | Default |
|----------|-------------|---------|
| `SPYGLASSES_API_KEY` | Your Spyglasses API key | Required |
| `SPYGLASSES_DEBUG` | Enable debug logging | `false` |
| `SPYGLASSES_AUTO_SYNC` | Auto-sync patterns on startup | `true` |
| `SPYGLASSES_CACHE_TTL` | Pattern cache TTL in seconds | `86400` (24 hours) |
| `SPYGLASSES_COLLECT_ENDPOINT` | Custom collector endpoint | `https://www.spyglasses.io/api/collect` |
| `SPYGLASSES_PATTERNS_ENDPOINT` | Custom patterns endpoint | `https://www.spyglasses.io/api/patterns` |

## Deployment

### Heroku

Add your API key to Heroku config vars:

```bash
heroku config:set SPYGLASSES_API_KEY=your_api_key_here
```

### Docker

Add environment variables to your Dockerfile:

```dockerfile
ENV SPYGLASSES_API_KEY=your_api_key_here
ENV SPYGLASSES_DEBUG=false
```

Or use docker-compose:

```yaml
services:
  web:
    build: .
    environment:
      - SPYGLASSES_API_KEY=your_api_key_here
      - SPYGLASSES_DEBUG=false
```

### AWS/EC2

Set environment variables in your deployment configuration or use AWS Systems Manager Parameter Store:

```bash

```

### DigitalOcean App Platform

Add environment variables in your app configuration:

```yaml
# .do/app.yaml
name: my-app
services:
- name: web
  environment_slug: ruby
  envs:
  - key: SPYGLASSES_API_KEY
    value: your_api_key_here
```

## Performance Considerations

The Spyglasses middleware is designed for high-performance Ruby applications:

- **Minimal Overhead**: Typically under 1ms per request
- **Background Logging**: API calls run in background threads
- **Smart Exclusions**: Static assets automatically excluded
- **Pattern Caching**: Compiled regex patterns are cached

### Thread Safety

The middleware is thread-safe and works well with:
- **Puma**: Multi-threaded web server
- **Unicorn**: Multi-process web server  
- **Passenger**: Both threading and forking modes

## Testing

In your test environment, disable API calls:

```ruby
# spec/spec_helper.rb or test/test_helper.rb
require 'spyglasses'

# Disable API calls in tests
Spyglasses.configure do |config|
  config.api_key = nil
  config.auto_sync = false
end
```

For RSpec, you might want to stub API calls:

```ruby
# spec/spec_helper.rb
require 'webmock/rspec'

RSpec.configure do |config|
  config.before(:each) do
    stub_request(:get, "https://www.spyglasses.io/api/patterns")
    stub_request(:post, "https://www.spyglasses.io/api/collect")
  end
end
```

## Manual Usage

You can also use Spyglasses outside of the middleware for manual detection:

```ruby
require 'spyglasses'

# Configure the client
client = Spyglasses::Client.new

# Detect bots
result = client.detect_bot('GPTBot/1.0')
puts "Bot detected: #{result.is_bot}"

# Detect AI referrers  
result = client.detect_ai_referrer('https://chat.openai.com/')
puts "AI referrer: #{result.source_type}"

# Combined detection
result = client.detect('Mozilla/5.0', 'https://chat.openai.com/')
puts "Source: #{result.source_type}"
```

## Verifying Installation

After deploying your Ruby application with Spyglasses, verify the installation by:

1. **Check logs** for Spyglasses initialization messages (if debug enabled)
2. **Visit your site** with different user agents to generate test traffic
3. **Monitor your dashboard** at [spyglasses.io](https://www.spyglasses.io) for incoming data

Enable debug mode temporarily to see detection in action:

```ruby
# Temporarily enable debug
Spyglasses.configure do |config|
  config.debug = true
end
```

## Troubleshooting

### Common Issues

**Gem not loading**
- Ensure gem is in your Gemfile and `bundle install` was run
- Check for conflicting gems or Ruby version issues

**API key not found**
- Verify `SPYGLASSES_API_KEY` environment variable is set
- Check for typos in the environment variable name
- Ensure deployment includes environment variables

**Middleware not detecting traffic**
- Verify middleware is properly added to your application
- Check exclude_paths configuration for overly broad exclusions
- Enable debug mode to see processing logs

**Performance issues**
- Review exclude_paths to ensure static assets are excluded
- Monitor background thread performance in production
- Check network latency to Spyglasses endpoints

**Rails-specific issues**
- Ensure middleware is added in the correct location
- Check for conflicts with other middleware (especially authentication)
- Verify Rails version compatibility (6.0+ recommended)

### Debug Mode

Enable debug logging to troubleshoot issues:

```ruby
Spyglasses.configure do |config|
  config.debug = true
end
```

This will output detailed logs about:
- Pattern loading and synchronization
- Request processing and detection results
- API communication attempts and responses

### Memory Usage

If you notice memory issues:
- Monitor pattern cache size
- Check for thread leaks in background logging
- Consider adjusting cache TTL for frequent pattern updates

Need help? Contact support@spyglasses.io
