robust_server_socket 0.3.1 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37064c5a03f119d17df76cb2eba1bd14b91d0cb4732f0d4aa29505614131966f
-  data.tar.gz: b18b44079588faf7a38979174971f928f50eb5c1535f0fc6ade2980ace6ed771
+  metadata.gz: 626993a0fda547dc940291eb09015b688a1f761cb5345664488996ed28a1906c
+  data.tar.gz: c5bb810563a9e6682c021b6553296477b3e34ecffeeecc2121534b8e397c7377
 SHA512:
-  metadata.gz: 91e42034b36683bfb0d7c481e9f9ef0e3acfae64d43214c0631bf797dbcbd94756e57288cf9a23f2cff2fccea307f019f0ffa93bfea5f86df2f4e751b171fd87
-  data.tar.gz: cd15f31a2c698f54684912f1ba3a1b87e8cca074ae0e0967b3374e861484d8bd45a546df35f42781beb651f4505d439ffbff643c3bb6db662fbe4666a87a7a83
+  metadata.gz: 9361de5026c683ce6e4a92aad34b8a3358248f4774bff96eb423148ee5daf2556fe1c16f7bd98658acba11218b1e6eae67f8f3af714970474070aa256132e2e7
+  data.tar.gz: a24681663c355f6117040fcaa538b73fa5bf9a4ff43edf6e962c9d8a3727e2d107bc222233efddffefd5fdb76a282c16c56e1c7eb323488168274175e0f29993

data/README.en.md

@@ -0,0 +1,652 @@
+# RobustServerSocket
+
+Gem for inter-service authorization, used in pair with RobustClientSocket
+
+### ⚠️ Not Production Tested (yet)
+
+## 📋 Table of Contents
+
+- [Security Features](#security-features)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Usage](#usage)
+- [Error Handling](#error-handling)
+
+## 🔒 Security Features
+
+RobustServerSocket implements a multi-layered protection system for inter-service communications:
+
+### 1. Cryptographic Protection
+- **RSA-2048 Encryption**: Uses RSA key pairs with minimum 2048-bit length
+- **Key Validation**: Automatic key size verification during configuration
+- **Asymmetric Encryption**: Private key on server, public keys on clients
+
+### 2. Token Reuse Protection
+- **One-time Tokens**: Each token can only be used once
+- **Redis Blacklist**: Used tokens are automatically added to blacklist
+- **Atomic Verification**: Race conditions prevented via Redis Lua scripts
+
+### 3. Time-based Restrictions
+- **Expiration Time**: Configurable token lifetime
+- **Automatic Expiration**: Tokens automatically become invalid after expiration
+- **Replay Attack Protection**: Old tokens cannot be reused
+
+### 4. Access Control
+- **Client Whitelist**: Only authorized services can connect
+- **Name-based Identification**: Each client must be explicitly listed in `allowed_services`
+- **Token Format Validation**: Strict token structure verification
+
+### 5. Rate Limiting (optional)
+- **DDoS Protection**: Limit number of requests from each client
+- **Sliding Window**: Fair distribution of requests over time
+- **Fail-open Strategy**: If Redis is unavailable, requests are allowed (for reliability)
+- **Per-client Limits**: Individual counters for each client
+
+### 6. Injection Protection
+- **Input Validation**: Type, length, and format verification of tokens
+- **Maximum Token Length**: 2048 character limit
+- **Empty Value Checks**: Rejection of empty or malformed tokens
+
+## 📦 Installation
+
+Add to Gemfile:
+
+```ruby
+gem 'robust_server_socket'
+```
+
+Then execute:
+
+```bash
+bundle install
+```
+
+## ⚙️ Configuration
+
+Create file `config/initializers/robust_server_socket.rb`:
+
+```ruby
+RobustServerSocket.configure do |c|
+  # REQUIRED PARAMETERS
+  
+  # Service private key (RSA-2048 or higher)
+  # IMPORTANT: Store in environment variables, DO NOT commit to git!
+  c.private_key = ENV['ROBUST_SERVER_PRIVATE_KEY']
+  
+  # Token lifetime in seconds
+  # Recommendation: 1-3 seconds for production (time from client request to server)
+  c.token_expiration_time = 3
+  
+  # List of allowed services (whitelist)
+  # Must match names in client keychain
+  c.allowed_services = %w[core payments notifications]
+  
+  # Redis for storing used tokens
+  c.redis_url = ENV.fetch('REDIS_URL', 'redis://localhost:6379/0')
+  c.redis_pass = ENV['REDIS_PASSWORD'] # can be nil for local development
+  
+  # OPTIONAL PARAMETERS: Rate Limiting
+  
+  # Enable rate limiting (default: false)
+  c.rate_limit_enabled = true
+  
+  # Maximum requests per time window (default: 100)
+  c.rate_limit_max_requests = 100
+  
+  # Time window size in seconds (default: 60)
+  c.rate_limit_window_seconds = 60
+end
+
+# Load configuration with validation
+RobustServerSocket.load!
+```
+
+## 🚀 Usage
+
+### Basic Authorization
+
+```ruby
+# In controller or middleware
+class ApiController < ApplicationController
+  before_action :authenticate_service!
+  
+  private
+  
+  def authenticate_service!
+    # Header configured in RobustClientSocket (SECURE-TOKEN default)
+    token = request.headers['SECURE-TOKEN']&.sub(/^Bearer /, '')
+    
+    @current_service = RobustServerSocket::ClientToken.validate!(token) # bang method (raises errors)
+  rescue RobustServerSocket::ClientToken::InvalidToken
+    render json: { error: 'Invalid token' }, status: :unauthorized
+  rescue RobustServerSocket::ClientToken::UnauthorizedClient
+    render json: { error: 'Unauthorized service' }, status: :forbidden
+  rescue RobustServerSocket::ClientToken::UsedToken
+    render json: { error: 'Token already used' }, status: :unauthorized
+  rescue RobustServerSocket::ClientToken::StaleToken
+    render json: { error: 'Token expired' }, status: :unauthorized
+  rescue RobustServerSocket::RateLimiter::RateLimitExceeded => e
+    render json: { error: e.message }, status: :too_many_requests
+  end
+  
+  def authenticate_service
+    token = request.headers['SECURE-TOKEN']&.sub(/^Bearer /, '')
+    @current_service = RobustServerSocket::ClientToken.new(token)
+    
+    if @current_service.valid? # doesn't raise errors
+      # Token is valid
+    else
+      # Token is invalid
+      render json: { error: 'Unauthorized' }, status: :unauthorized
+    end
+  end
+end
+```
+
+### Advanced Usage
+
+```ruby
+# Create token object
+token_string = request.headers['SECURE-TOKEN']&.sub(/^Bearer /, '')
+client_token = RobustServerSocket::ClientToken.new(token_string)
+
+# Check validity (returns true/false)
+if client_token.valid?
+  # Get client name
+  client_name = client_token.client
+  puts "Authorized client: #{client_name}"
+else
+  # Token is invalid
+  render json: { error: 'Unauthorized' }, status: :unauthorized
+end
+
+# Quick validation with exceptions (recommended)
+begin
+  service_token = RobustServerSocket::ClientToken.validate!(token_string)
+  client_name = service_token.client
+rescue => e
+  # Handle specific errors
+end
+```
+
+### Manual Rate Limiting
+
+```ruby
+# Check current attempt count
+attempts = RobustServerSocket::RateLimiter.current_attempts('core')
+puts "Core service made #{attempts} requests"
+
+# Reset counter for specific client
+RobustServerSocket::RateLimiter.reset!('core')
+
+# Check with exception on exceeded limit
+begin
+  RobustServerSocket::RateLimiter.check!('core')
+rescue RobustServerSocket::RateLimiter::RateLimitExceeded => e
+  puts e.message # "Rate limit exceeded for core: 101/100 requests per 60s"
+end
+
+# Check without exception (returns false when exceeded)
+if RobustServerSocket::RateLimiter.check('core')
+  # Limit not exceeded
+else
+  # Limit exceeded
+end
+```
+
+## 🚦 Rate Limiting (Request Rate Limiting)
+
+### How It Works
+
+Rate Limiter protects your service from overload by limiting the number of requests from each client within a time window.
+
+**Characteristics:**
+- **Per-client counters**: Separate counter for each service
+- **Sliding window**: Window resets automatically after time expires
+- **Atomicity**: Increment and check are performed atomically (Redis LUA script)
+- **Fail-open**: When Redis is unavailable, requests are allowed (not blocked)
+
+### Limit Configuration
+
+```ruby
+RobustServerSocket.configure do |c|
+  # Enable rate limiting
+  c.rate_limit_enabled = true
+
+  # For low-traffic microservices
+  c.rate_limit_max_requests = 50
+  c.rate_limit_window_seconds = 60
+end
+```
+
+### Monitoring
+
+```ruby
+# Check current state
+clients = ['core', 'payments', 'notifications']
+clients.each do |client|
+  attempts = RobustServerSocket::RateLimiter.current_attempts(client)
+  max = RobustServerSocket.configuration.rate_limit_max_requests
+  puts "#{client}: #{attempts}/#{max}"
+end
+
+# In metrics (Prometheus, StatsD, etc.)
+clients.each do |client|
+  attempts = RobustServerSocket::RateLimiter.current_attempts(client)
+  Metrics.gauge("rate_limiter.attempts.#{client}", attempts)
+end
+```
+
+## ❌ Error Handling
+
+### Exception Types
+
+| Exception | Reason | HTTP Status | Action |
+|-----------|--------|-------------|--------|
+| `InvalidToken` | Token cannot be decrypted or has invalid format | 401 | Check token and key correctness |
+| `UnauthorizedClient` | Client not in whitelist | 403 | Add client to `allowed_services` |
+| `UsedToken` | Token has already been used | 401 | Client must request new token |
+| `StaleToken` | Token has expired | 401 | Client must request new token |
+| `RateLimitExceeded` | Rate limit exceeded | 429 | Client should wait or retry later |
+
+### Centralized Error Handling
+
+```ruby
+# In ApplicationController
+rescue_from RobustServerSocket::ClientToken::InvalidToken,
+            RobustServerSocket::ClientToken::UsedToken,
+            RobustServerSocket::ClientToken::StaleToken,
+            with: :unauthorized_response
+
+rescue_from RobustServerSocket::ClientToken::UnauthorizedClient,
+            with: :forbidden_response
+
+rescue_from RobustServerSocket::RateLimiter::RateLimitExceeded,
+            with: :rate_limit_response
+
+private
+
+def unauthorized_response(exception)
+  render json: {
+    error: 'Authentication failed',
+    message: exception.message,
+    type: exception.class.name
+  }, status: :unauthorized
+end
+
+def forbidden_response(exception)
+  render json: {
+    error: 'Access denied',
+    message: exception.message,
+    type: exception.class.name
+  }, status: :forbidden
+end
+
+def rate_limit_response(exception)
+  render json: {
+    error: 'Too many requests',
+    message: exception.message,
+    type: exception.class.name,
+    retry_after: RobustServerSocket.configuration.rate_limit_window_seconds
+  }, status: :too_many_requests
+end
+```
+
+## 💡 Usage Recommendations
+
+### 1. Key Management
+
+**✅ DO:**
+```ruby
+# Store keys in environment variables
+c.private_key = ENV['ROBUST_SERVER_PRIVATE_KEY']
+
+# Use secrets management (AWS Secrets Manager, Vault, etc.)
+c.private_key = Rails.application.credentials.dig(:robust_server, :private_key)
+
+# Generate keys correctly
+# openssl genrsa -out private_key.pem 2048
+# openssl rsa -in private_key.pem -pubout -out public_key.pem
+```
+
+**❌ DON'T:**
+```ruby
+# DON'T commit keys to git
+c.private_key = "-----BEGIN PRIVATE KEY-----\nMII..."
+
+# DON'T use weak keys
+# Minimum RSA-2048, RSA-4096 recommended for high security
+```
+
+### 2. Redis Configuration
+
+**✅ DO:**
+```ruby
+# Use separate namespace for each environment
+c.redis_url = ENV.fetch('REDIS_URL', 'redis://localhost:6379/0')
+
+# Configure connection pool in production
+# In config/initializers/redis.rb
+Redis.current = ConnectionPool.new(size: 5, timeout: 5) do
+  Redis.new(url: ENV['REDIS_URL'], password: ENV['REDIS_PASSWORD'])
+end
+
+# Monitor Redis status
+# Use Redis Sentinel or Cluster for high availability
+```
+
+**❌ DON'T:**
+```ruby
+# DON'T use same Redis DB for all environments, use separate Redis DB
+# DON'T ignore Redis errors (rate limiter is already fail-open, but log them)
+```
+
+### 5. Service Whitelist
+
+```ruby
+# Explicitly specify only necessary services
+c.allowed_services = %w[core payments] # ✅
+
+# DON'T use wildcards or regular expressions
+c.allowed_services = %w[*] # ❌ DANGEROUS!
+
+# Synchronize with client keychain
+# Server (robust_server_socket):
+c.allowed_services = %w[core]
+
+# Client (robust_client_socket):
+c.keychain = {
+  core: { # ← Must match
+    base_uri: 'https://core.example.com',
+    public_key: '-----BEGIN PUBLIC KEY-----...'
+  }
+}
+```
+
+## 🤝 Integration with RobustClientSocket
+
+For full functionality, configure the client side:
+
+```ruby
+# On client (RobustClientSocket)
+RobustClientSocket.configure do |c|
+  c.service_name = 'core' # ← Must be in server's allowed_services
+  c.keychain = {
+    payments: {
+      base_uri: 'https://payments.example.com',
+      public_key: '-----BEGIN PUBLIC KEY-----...' # Public key of payments server
+    }
+  }
+end
+
+# On server (RobustServerSocket)
+RobustServerSocket.configure do |c|
+  c.allowed_services = %w[core] # ← Matches client's service_name
+  c.private_key = '-----BEGIN PRIVATE KEY-----...' # Private pair to public_key
+end
+```
+
+## 📚 Additional Resources
+
+- [RobustClientSocket documentation](https://github.com/tee0zed/robust_client_socket)
+- [RSA encryption best practices](https://www.openssl.org/docs/)
+- [Redis security guide](https://redis.io/topics/security)
+
+## 📝 License
+
+See [MIT-LICENSE](MIT-LICENSE) file
+
+## 🐛 Bugs and Suggestions
+
+Report issues through your repository's issue tracker.
+
+
+#### Test: 1000 Requests with Token Validation
+
+**Without RobustServerSocket (plain HTTP controller):**
+```ruby
+Benchmark.measure do
+  1000.times do
+    # Regular request without authorization
+    get '/api/v1/partners/719a68e4-3457-45dd-8d7f-73f1d367b87a/merchants'
+  end
+end
+```
+
+**Results (approximate):**
+- **Real time**: ~2.5 seconds
+- No token verification
+- No RSA decryption
+- No Redis checks
+
+---
+
+**With RobustServerSocket (full protection):**
+```ruby
+Benchmark.measure do
+  1000.times do
+    # Request with RobustClientSocket (RSA + tokens)
+    RobustClientSocket::CoreApi.get('/api/v1/partners/719a68e4-3457-45dd-8d7f-73f1d367b87a/merchants')
+  end
+end
+```
+
+**Results:**
+- **Real time**: 2.77 seconds
+- **User CPU**: 0.23 seconds
+- **System CPU**: 0.54 seconds
+- **Total CPU**: 0.77 seconds
+
+### 📊 Security Overhead Analysis
+
+| Operation | Time | % of Request |
+|-----------|------|-------------|
+| **RSA Decryption** | ~0.1-0.2ms | 3-7% |
+| **Redis Token Check** | ~0.05-0.1ms | 2-3% |
+| **Rate Limiting** | ~0.02-0.05ms | 1% |
+| **Whitelist Validation** | <0.01ms | <1% |
+| **Total Overhead** | **~0.2-0.4ms** | **~10-15%** |
+
+### 🎯 Key Findings
+
+1. **Minimal overhead (~0.3ms per request)**
+   - RSA-2048 decryption: ~0.15ms
+   - Redis operations: ~0.08ms
+   - Rate limiting: ~0.03ms
+   
+2. **Scales linearly**
+   - 100 req/s = +30ms overhead
+   - 1000 req/s = +300ms overhead
+   - Acceptable for most applications
+
+3. **Redis is main bottleneck**
+   - Use Redis Sentinel/Cluster
+   - Connection pooling is critical
+   - Fail-open strategy for reliability
+
+### 💡 Performance Optimization
+
+**1. Redis Connection Pool:**
+
+```ruby
+# config/initializers/redis.rb
+require 'connection_pool'
+
+REDIS_POOL = ConnectionPool.new(size: 25, timeout: 5) do
+  Redis.new(
+    url: ENV['REDIS_URL'],
+    password: ENV['REDIS_PASSWORD'],
+    reconnect_attempts: 3,
+    reconnect_delay: 0.5,
+    reconnect_delay_max: 5.0
+  )
+end
+
+# In RobustServerSocket::SecureToken::Cacher
+def self.with_redis
+  REDIS_POOL.with do |redis|
+    yield redis
+  end
+end
+```
+
+**2. Public Key Caching:**
+
+```ruby
+# Keys are already cached at load!, but can be optimized
+class RobustServerSocket::ClientToken
+  # Keys are loaded once at application startup
+  # No additional optimization needed
+end
+```
+
+**3. Rate Limiting Optimization:**
+
+```ruby
+RobustServerSocket.configure do |c|
+  # For high-load systems
+  c.rate_limit_enabled = true
+  c.rate_limit_max_requests = 1000  # Increase limit
+  c.rate_limit_window_seconds = 60
+  
+  # For low-load systems
+  c.rate_limit_max_requests = 100
+  c.rate_limit_window_seconds = 60
+end
+```
+
+**4. Token Expiration Optimization:**
+
+```ruby
+# Short lifetime = more requests for new tokens
+c.token_expiration_time = 10.minutes  # ❌ High traffic
+
+# Optimal time for inter-service calls
+c.token_expiration_time = 3  # ✅ 3 seconds is enough
+```
+
+### 🔬 Performance Monitoring
+
+**Metrics to Track:**
+
+```ruby
+class ApiController < ApplicationController
+  around_action :track_auth_performance
+  
+  private
+  
+  def track_auth_performance
+    start = Time.now
+    
+    begin
+      yield
+    ensure
+      duration = ((Time.now - start) * 1000).round(2)
+      
+      # Total request time
+      Metrics.timing('request.duration', duration, tags: [
+        "controller:#{controller_name}",
+        "action:#{action_name}"
+      ])
+      
+      # Authentication attempts
+      if @current_service
+        Metrics.increment('auth.success', tags: ["service:#{@current_service.client}"])
+      else
+        Metrics.increment('auth.failure')
+      end
+    end
+  end
+end
+
+# Specific metrics for RobustServerSocket
+module RobustServerSocket
+  class ClientToken
+    def self.validate_with_metrics!(token)
+      start = Time.now
+      result = validate!(token)
+      duration = ((Time.now - start) * 1000).round(2)
+      
+      Metrics.timing('robust_server.validation.duration', duration)
+      result
+    rescue StandardError => e
+      Metrics.increment('robust_server.validation.error', tags: ["error:#{e.class.name}"])
+      raise
+    end
+  end
+end
+```
+
+### 📈 Performance at Different Loads
+
+| Req/s | Without Protection | With RobustServerSocket | Overhead | Acceptable |
+|-------|-------------------|------------------------|----------|-----------|
+| 10 | 100ms | 103ms | 3ms | ✅ Excellent |
+| 100 | 1s | 1.03s | 30ms | ✅ Excellent |
+| 500 | 5s | 5.15s | 150ms | ✅ Good |
+| 1,000 | 10s | 10.3s | 300ms | ✅ Acceptable |
+| 5,000 | 50s | 51.5s | 1.5s | ⚠️ Redis scaling needed |
+| 10,000 | 100s | 103s | 3s | ⚠️ Need Redis Cluster |
+
+**Conclusion:** Up to 1000 req/s - excellent performance. Higher loads require Redis scaling.
+
+### 🚀 Production Recommendations
+
+**For high-load systems (>1000 req/s):**
+
+1. **Redis Cluster** - distributed load
+2. **Connection Pool** - minimum 25-50 connections
+3. **Monitor Redis** - latency, memory, connections
+4. **Fail-over Strategy** - Redis Sentinel
+5. **CDN for static** - reduce overall load
+
+**For medium load (100-1000 req/s):**
+
+1. **Standalone Redis** with persistence
+2. **Connection Pool** - 10-25 connections
+3. **Basic monitoring**
+4. **Rate limiting** - spike protection
+
+**For low load (<100 req/s):**
+
+1. **Simple Redis** setup
+2. **Default connection pool** (5)
+3. **Standard configuration**
+
+## 🤝 Integration with RobustClientSocket
+
+For full functionality, configure the client side:
+
+```ruby
+# On client (RobustClientSocket)
+RobustClientSocket.configure do |c|
+  c.service_name = 'core' # ← Must be in server's allowed_services
+  c.keychain = {
+    payments: {
+      base_uri: 'https://payments.example.com',
+      public_key: '-----BEGIN PUBLIC KEY-----...' # Public key of payments server
+    }
+  }
+end
+
+# On server (RobustServerSocket)
+RobustServerSocket.configure do |c|
+  c.allowed_services = %w[core] # ← Matches client's service_name
+  c.private_key = '-----BEGIN PRIVATE KEY-----...' # Private pair to public_key
+end
+```
+
+## 📚 Additional Resources
+
+- [BENCHMARK_ANALYSIS.md](BENCHMARK_ANALYSIS.md)
+- [RobustClientSocket documentation](../robust_client_socket/README.md)
+- [RSA encryption best practices](https://www.openssl.org/docs/)
+- [Redis security guide](https://redis.io/topics/security)
+
+## 📝 License
+
+See [MIT-LICENSE](MIT-LICENSE) file
+
+## 🐛 Bugs and Suggestions
+
+Report issues through your repository's issue tracker.

data/README.md

@@ -1,59 +1,387 @@
 # RobustServerSocket
 
-Gem for in-service Authorization for using with RobustClientSocket
+Gem для межсервисной авторизации, используется в паре с RobustClientSocket
 
-## Security
+### ⚠️ Not Production Tested (yet)
 
-- RSA-2048 key pair is used for authorization.
-- Authorized client names are stored in token and config
-- Token is staleable
-- Token if one-time use only
-- Blacklist for tokens in redis
+## 📋 Содержание
 
-## Usage
+- [Функции безопасности](#функции-безопасности)
+- [Установка](#установка)
+- [Конфигурация](#конфигурация)
+- [Использование](#использование)
+- [Обработка ошибок](#обработка-ошибок)
 
-'config/initializers/robust_server_socket.rb'
+## 🔒 Функции безопасности
+
+RobustServerSocket реализует многоуровневую систему защиты для межсервисных коммуникаций:
+
+### 1. Криптографическая защита
+- **RSA-2048 шифрование**: Используется пара ключей RSA с минимальной длиной 2048 бит
+- **Валидация ключей**: Автоматическая проверка размера ключа при конфигурации
+- **Асимметричное шифрование**: Приватный ключ на сервере, публичный — у клиентов
+
+### 2. Защита от повторного использования токенов
+- **Одноразовые токены**: Каждый токен может быть использован только один раз
+- **Blacklist в Redis**: Использованные токены автоматически добавляются в черный список
+- **Атомарная проверка**: Race condition защищена благодаря Redis Lua скриптам
+
+### 3. Временные ограничения
+- **Expiration time**: Настраиваемое время жизни токена
+- **Автоматическое истечение**: Токены автоматически становятся недействительными после истечения времени
+- **Защита от replay attacks**: Старые токены не могут быть использованы повторно
+
+### 4. Контроль доступа
+- **Whitelist клиентов**: Только авторизованные сервисы могут подключаться
+- **Идентификация по имени**: Каждый клиент должен быть явно указан в `allowed_services`
+- **Валидация формата токена**: Строгая проверка структуры токена
+
+### 5. Rate Limiting (опционально)
+- **Защита от DDoS**: Ограничение количества запросов от каждого клиента
+- **Sliding window**: Справедливое распределение запросов во времени
+- **Fail-open стратегия**: Если Redis недоступен, запросы пропускаются (для надёжности)
+- **Per-client лимиты**: Индивидуальные счётчики для каждого клиента
+
+### 6. Защита от инъекций
+- **Валидация входных данных**: Проверка типа, длины и формата токенов
+- **Максимальная длина токена**: Ограничение 2048 символов
+- **Проверка на пустые значения**: Отклонение пустых или некорректных токенов
+
+## 📦 Установка
+
+```ruby
+gem 'robust_server_socket'
+```
+
+## ⚙️ Конфигурация
+
+Создайте файл `config/initializers/robust_server_socket.rb`:
 
 ```ruby
 RobustServerSocket.configure do |c|
-  c.private_key = '-----PRIVATE KEY-----[...]' # private key of the service, from pair of keys by RobustServerSocket
-  c.token_expiration_time = 10.minutes # time in seconds for token expiration
-  c.allowed_services = %w(core) # list of services allowed to use this service, must be same as service name in keychain in RobustClientSocket
-  # so if we have 
-  # RobustClientSocket.configure do |c|
-  # c.keychain = {
-  #   core: { <<< service name
-  #           base_uri: 'https://core.payrent.com',
-  #           public_key: '-----BEGIN PUBLIC KEY-----[...]'
-  #   },
-  # we should add 'core' to allowed_services
-  c.redis_url = 'redis://localhost:6379' # redis url for storing tokens
-  c.redis_pass = 'password' # redis password
+  # ОБЯЗАТЕЛЬНЫЕ ПАРАМЕТРЫ
   
-  # Optional: Rate Limiting (disabled by default)
-  c.rate_limit_enabled = true # enable rate limiting per client
-  c.rate_limit_max_requests = 100 # maximum requests per window (default: 100)
-  c.rate_limit_window_seconds = 60 # time window in seconds (default: 60)
-end
+  # Приватный ключ сервиса (RSA-2048 или выше)
+  c.private_key = ENV['ROBUST_SERVER_PRIVATE_KEY']
+  c.token_expiration_time = 3
   
+  # Список разрешённых сервисов (whitelist)
+  # Должен совпадать с именами RobustClientSocket клиента
+  c.allowed_services = %w[core payments notifications]
+  
+  # Redis для работы replay-attack protection и throttling
+  c.redis_url = ENV.fetch('REDIS_URL', 'redis://localhost:6379/0')
+  c.redis_pass = ENV['REDIS_PASSWORD']
+
+  # НЕОБЯЗАТЕЛЬНЫЕ ПАРАМЕТРЫ
+  # Включить ограничение частоты запросов (по умолчанию: false)
+  c.rate_limit_enabled = true
+  # Максимальное количество запросов в окне времени (по умолчанию: 100)
+  c.rate_limit_max_requests = 100
+  # Размер временного окна в секундах (по умолчанию: 60)
+  c.rate_limit_window_seconds = 60
+end
+
+# Загрузка конфигурации с валидацией
 RobustServerSocket.load!
 ```
 
-and then
+### Опции конфигурации сервиса
+
+| Параметр | Тип | Обязательный | Default | Описание |
+|----------|-----|--------------|---------|----------|
+| `private_key` | String | ✅ | - | Приватный RSA ключ сервиса (RSA-2048 или выше) |
+| `token_expiration_time` | Integer | ✅ | - | Время жизни токена в секундах |
+| `allowed_services` | Array | ✅ | - | Список разрешённых сервисов (whitelist) |
+| `redis_url` | String | ✅ | - | URL для подключения к Redis |
+| `redis_pass` | String | ❌ | nil | Пароль для Redis (если требуется) |
+| `rate_limit_enabled` | Boolean | ❌ | false | Включить ограничение частоты запросов |
+| `rate_limit_max_requests` | Integer | ❌ | 100 | Максимальное количество запросов в окне времени |
+| `rate_limit_window_seconds` | Integer | ❌ | 60 | Размер временного окна в секундах |
+
+## 🚀 Использование
+
+### Базовая авторизация
+
+```ruby
+# В контроллере или middleware
+class ApiController < ApplicationController
+  before_action :authenticate_service!
+  
+  private
+  
+  def authenticate_service!
+    # Хедер, прописанный в RobustClientSocket (SECURE-TOKEN default)
+    token = request.headers['SECURE-TOKEN']&.sub(/^Bearer /, '')
+    
+    @current_service = RobustServerSocket::ClientToken.validate!(token) # bang method (рейзит ошибки)
+  rescue RobustServerSocket::ClientToken::InvalidToken
+    render json: { error: 'Invalid token' }, status: :unauthorized
+  rescue RobustServerSocket::ClientToken::UnauthorizedClient
+    render json: { error: 'Unauthorized service' }, status: :forbidden
+  rescue RobustServerSocket::ClientToken::UsedToken
+    render json: { error: 'Token already used' }, status: :unauthorized
+  rescue RobustServerSocket::ClientToken::StaleToken
+    render json: { error: 'Token expired' }, status: :unauthorized
+  rescue RobustServerSocket::RateLimiter::RateLimitExceeded => e
+    render json: { error: e.message }, status: :too_many_requests
+  end
+  
+  def authenticate_service
+    token = request.headers['SECURE-TOKEN']&.sub(/^Bearer /, '')
+    @current_service = RobustServerSocket::ClientToken.valid?(token) # не рейзит
+    
+    if @current_service
+      # Токен валиден
+    else
+      # Токен невалиден
+      render json: { error: 'Unauthorized' }, status: :unauthorized
+    end
+  end
+end
+```
+
+### Расширенное использование
+
+```ruby
+# Создание объекта токена
+token_string = request.headers['Authorization']&.sub(/^Bearer /, '')
+client_token = RobustServerSocket::ClientToken.new(token_string)
+
+# Проверка валидности (возвращает true/false)
+if client_token.valid?
+  # Получение имени клиента
+  client_name = client_token.client
+  puts "Authorized client: #{client_name}"
+else
+  # Токен невалиден
+  render json: { error: 'Unauthorized' }, status: :unauthorized
+end
+
+# Быстрая валидация с исключениями
+begin
+  service_token = RobustServerSocket::ClientToken.validate!(token_string)
+  client_name = service_token.client
+rescue => e
+  # Обработка специфичных ошибок
+end
+```
+
+### Rate Limiting вручную
+
+```ruby
+# Проверка текущего количества попыток
+attempts = RobustServerSocket::RateLimiter.current_attempts('core')
+puts "Core service made #{attempts} requests"
+
+# Сброс счётчика для конкретного клиента
+RobustServerSocket::RateLimiter.reset!('core')
+
+# Проверка с исключением при превышении
+begin
+  RobustServerSocket::RateLimiter.check!('core')
+rescue RobustServerSocket::RateLimiter::RateLimitExceeded => e
+  puts e.message # "Rate limit exceeded for core: 101/100 requests per 60s"
+end
+
+# Проверка без исключения (возвращает false при превышении)
+if RobustServerSocket::RateLimiter.check('core')
+  # Лимит не превышен
+else
+  # Лимит превышен
+end
+```
+
+## 🚦 Rate Limiting (Ограничение частоты запросов)
+
+### Принцип работы
+
+Rate Limiter защищает ваш сервис от перегрузки, ограничивая количество запросов от каждого клиента в определённом временном окне.
+
+**Характеристики:**
+- **Per-client counters**: Отдельный счётчик для каждого сервиса
+- **Sliding window**: Окно сбрасывается автоматически после истечения времени
+- **Атомарность**: Инкремент и проверка выполняются атомарно (Redis LUA script)
+- **Fail-open**: При недоступности Redis запросы пропускаются (не блокируются)
+
+### Мониторинг
+
+```ruby
+# Проверка текущего состояния
+clients = ['core', 'payments', 'notifications']
+clients.each do |client|
+  attempts = RobustServerSocket::RateLimiter.current_attempts(client)
+  max = RobustServerSocket.configuration.rate_limit_max_requests
+  puts "#{client}: #{attempts}/#{max}"
+end
+
+# В метриках (Prometheus, StatsD и т.д.)
+clients.each do |client|
+  attempts = RobustServerSocket::RateLimiter.current_attempts(client)
+  Metrics.gauge("rate_limiter.attempts.#{client}", attempts)
+end
+```
+
+## ❌ Обработка ошибок
+
+### Типы исключений
+
+| Исключение | Причина | HTTP статус | Действие |
+|-----------|---------|-------------|----------|
+| `InvalidToken` | Токен не может быть расшифрован или имеет неверный формат | 401 | Проверьте корректность токена и ключей |
+| `UnauthorizedClient` | Клиент не в whitelist | 403 | Добавьте клиента в `allowed_services` |
+| `UsedToken` | Токен уже был использован | 401 | Клиент должен запросить новый токен |
+| `StaleToken` | Токен истёк | 401 | Клиент должен запросить новый токен |
+| `RateLimitExceeded` | Превышен лимит запросов | 429 | Клиент должен подождать или ретраить позже |
+
+### Централизованная обработка
+
+```ruby
+# В ApplicationController
+rescue_from RobustServerSocket::ClientToken::InvalidToken,
+            RobustServerSocket::ClientToken::UsedToken,
+            RobustServerSocket::ClientToken::StaleToken,
+            with: :unauthorized_response
+
+rescue_from RobustServerSocket::ClientToken::UnauthorizedClient,
+            with: :forbidden_response
+
+rescue_from RobustServerSocket::RateLimiter::RateLimitExceeded,
+            with: :rate_limit_response
+
+private
+
+def unauthorized_response(exception)
+  render json: {
+    error: 'Authentication failed',
+    message: exception.message,
+    type: exception.class.name
+  }, status: :unauthorized
+end
+
+def forbidden_response(exception)
+  render json: {
+    error: 'Access denied',
+    message: exception.message,
+    type: exception.class.name
+  }, status: :forbidden
+end
+
+def rate_limit_response(exception)
+  render json: {
+    error: 'Too many requests',
+    message: exception.message,
+    type: exception.class.name,
+    retry_after: RobustServerSocket.configuration.rate_limit_window_seconds
+  }, status: :too_many_requests
+end
+```
+
+## 💡 Рекомендации по использованию
+
+### 1. Управление ключами
+
+**✅ DO:**
+```ruby
+# Храните ключи в переменных окружения
+c.private_key = ENV['ROBUST_SERVER_PRIVATE_KEY']
+
+# Используйте secrets management (AWS Secrets Manager, Vault, и т.д.)
+c.private_key = Rails.application.credentials.dig(:robust_server, :private_key)
+
+# Генерируйте ключи правильно
+# openssl genrsa -out private_key.pem 2048
+# openssl rsa -in private_key.pem -pubout -out public_key.pem
+```
+
+**❌ DON'T:**
+```ruby
+# НЕ коммитьте ключи в git
+c.private_key = "-----BEGIN PRIVATE KEY-----\nMII..."
+
+# НЕ используйте слабые ключи
+# Минимум RSA-2048, рекомендуется RSA-4096 для высокой безопасности
+```
+
+### 2. Конфигурация Redis
 
+**✅ DO:**
 ```ruby
-token = RobustServerSocket::ClientToken.new(token) # token - is a Bearer from secure-token header
-token.valid? #Boolean  check if token is not expired and client is allowed to use this service, main authorization check
-token.client #String  name of the client
+# Используйте отдельный namespace для каждого окружения
+c.redis_url = ENV.fetch('REDIS_URL', 'redis://localhost:6379/0')
+
+# Настройте connection pool в production
+# В config/initializers/redis.rb
+Redis.current = ConnectionPool.new(size: 5, timeout: 5) do
+  Redis.new(url: ENV['REDIS_URL'], password: ENV['REDIS_PASSWORD'])
+end
+
+# Мониторьте состояние Redis
+# Используйте Redis Sentinel или Cluster для высокой доступности
+```
 
-RobustServerSocket::ClientToken.validate!(token) # shortcut for token.valid? and raises specific errors
+**❌ DON'T:**
+```ruby
+# НЕ используйте одну БД Redis для всех окружений, используйте отдельную bd redis
+# НЕ игнорируйте ошибки Redis (rate limiter уже fail-open, но логируйте их)
 ```
-## Errors
 
-`RobustServerSocket::ClientToken::UnauthorizedClient` - client is not allowed to use this service you should add it to allowed_services
-`RobustServerSocket::ClientToken::UsedToken` - token is already used
-`RobustServerSocket::ClientToken::StaleToken` - token is stale over the expiration time
-`RobustServerSocket::ClientToken::InvalidToken` - token decryption failed
-`RobustServerSocket::ClientToken::RateLimitExceeded` - client exceeded rate limit (only when rate limiting is enabled)
+### 5. Whitelist сервисов
+
+```ruby
+# Явно указывайте только необходимые сервисы
+c.allowed_services = %w[core payments] # ✅
+
+# НЕ используйте wildcards или регулярные выражения
+c.allowed_services = %w[*] # ❌ ОПАСНО!
+
+# Синхронизируйте с keychain клиента
+# Server (robust_server_socket):
+c.allowed_services = %w[core]
+
+# Client (robust_client_socket):
+c.keychain = {
+  core: { # ← Должно совпадать
+    base_uri: 'https://core.example.com',
+    public_key: '-----BEGIN PUBLIC KEY-----...'
+  }
+}
+```
+
+## 🤝 Интеграция с RobustClientSocket
+
+Для полноценной работы необходимо настроить клиентскую часть:
+
+```ruby
+# На клиенте (RobustClientSocket)
+RobustClientSocket.configure do |c|
+  c.service_name = 'core' # ← Должно быть в allowed_services сервера
+  c.keychain = {
+    payments: {
+      base_uri: 'https://payments.example.com',
+      public_key: '-----BEGIN PUBLIC KEY-----...' # Публичный ключ сервера payments
+    }
+  }
+end
+
+# На сервере (RobustServerSocket)
+RobustServerSocket.configure do |c|
+  c.allowed_services = %w[core] # ← Соответствует service_name клиента
+  c.private_key = '-----BEGIN PRIVATE KEY-----...' # Приватная пара к public_key
+end
+```
+
+## 📚 Дополнительные ресурсы
+
+- [BENCHMARK_ANALYSIS.md](BENCHMARK_ANALYSIS.md)
+- [RobustClientSocket documentation](https://github.com/tee0zed/robust_client_socket)
+- [RSA encryption best practices](https://www.openssl.org/docs/)
+- [Redis security guide](https://redis.io/topics/security)
+
+## 📝 Лицензия
+
+См. файл [MIT-LICENSE](MIT-LICENSE)
 
+## 🐛 Баги и предложения
 
+Сообщайте о проблемах через issue tracker вашего репозитория.

data/lib/robust_server_socket/client_token.rb

@@ -13,23 +13,7 @@ module RobustServerSocket
 
     def self.validate!(secure_token)
       new(secure_token).tap do |instance|
-        raise InvalidToken unless instance.decrypted_token
-        raise UnauthorizedClient unless instance.client
-
-        RateLimiter.check!(instance.client)
-
-        result = instance.atomic_validate_and_log_token
-
-        case result
-        when 'stale'
-          raise StaleToken
-        when 'used'
-          raise UsedToken
-        when 'ok'
-          true
-        else
-          raise InvalidToken, "Unexpected validation result: #{result}"
-        end
+        instance.validate!
       end
     end
 
@@ -38,6 +22,26 @@ module RobustServerSocket
       @client = nil
     end
 
+    def validate!
+      raise InvalidToken unless decrypted_token
+      raise UnauthorizedClient unless client
+
+      RateLimiter.check!(client)
+
+      result = atomic_validate_and_log_token
+
+      case result
+      when 'stale'
+        raise StaleToken
+      when 'used'
+        raise UsedToken
+      when 'ok'
+        true
+      else
+        raise InvalidToken, "Unexpected validation result: #{result}"
+      end
+    end
+
     def valid?
       !!(decrypted_token &&
         client &&

data/lib/robust_server_socket.rb

@@ -17,6 +17,5 @@ module RobustServerSocket
 
     require_relative 'robust_server_socket/rate_limiter'
     require_relative 'robust_server_socket/client_token'
-    require_relative 'robust_server_socket/private_message'
   end
 end

data/lib/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RobustServerSocket
-  VERSION = '0.3.1'
+  VERSION = '0.3.3'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: robust_server_socket
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.3
 platform: ruby
 authors:
 - tee_zed
@@ -75,6 +75,7 @@ files:
 - ".rspec"
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
+- README.en.md
 - README.md
 - Rakefile
 - lib/robust_server_socket.rb