synthra 0.1.0

data/lib/synthra/api_server.rb

@@ -0,0 +1,718 @@
+# frozen_string_literal: true
+
+require "webrick"
+require "json"
+require "uri"
+require "openssl" # constant-time key comparison in #authenticate
+
+module Synthra
+  # Production API Server
+  #
+  # A production-ready API server for data generation.
+  # Designed to be the core of your data generation platform.
+  #
+  # @example Start standalone server
+  #   Synthra::APIServer.start(
+  #     schema_dir: "schemas/",
+  #     port: 3000,
+  #     environment: :production
+  #   )
+  #
+  # @example Use as Rack middleware
+  #   # config.ru
+  #   require 'synthra'
+  #   run Synthra::APIServer.rack_app(schema_dir: "schemas/")
+  #
+  # @example With authentication
+  #   Synthra::APIServer.start(
+  #     schema_dir: "schemas/",
+  #     auth: { type: :api_key, keys: ["secret-key-123"] }
+  #   )
+  #
+  class APIServer
+    VERSION = "1.0.0"
+    
+    attr_reader :registry, :config
+
+    # Server configuration defaults
+    DEFAULT_CONFIG = {
+      port: 3000,
+      host: "0.0.0.0",
+      environment: :development,
+      cors: true,
+      rate_limit: 0,
+      max_batch_size: 10_000,
+      max_stream_size: 1_000_000,
+      auth: nil,
+      log_level: :info,
+      request_timeout: 30,
+      enable_metrics: true,
+      enable_caching: false,
+      cache_ttl: 60
+    }.freeze
+
+    # Create a new API server
+    #
+    # @param schema_dir [String] directory containing DSL schemas
+    # @param config [Hash] server configuration
+    #
+    def initialize(schema_dir:, **config)
+      @config = DEFAULT_CONFIG.merge(config)
+      @registry = Registry.new
+      @registry.load_dir(schema_dir)
+      @metrics = Metrics.new if @config[:enable_metrics]
+      @cache = Cache.new(@config[:cache_ttl]) if @config[:enable_caching]
+      @rate_limiter = RateLimiter.new(@config[:rate_limit]) if @config[:rate_limit] > 0
+    end
+
+    # Start the server
+    def start
+      # :nocov: binds a real TCP port and blocks on WEBrick#start — exercised via integration use.
+      print_banner
+      setup_signal_handlers
+
+      @server = WEBrick::HTTPServer.new(
+        Port: @config[:port],
+        BindAddress: @config[:host],
+        Logger: create_logger,
+        AccessLog: []
+      )
+
+      @server.mount_proc("/", &method(:handle_request))
+      @server.start
+      # :nocov:
+    end
+
+    # Start in background
+    def start_async
+      # :nocov: spawns a thread that binds a port and sleeps — integration-only.
+      @thread = Thread.new { start }
+      sleep 0.5 # Wait for server to start
+      @thread
+      # :nocov:
+    end
+
+    # Stop the server
+    def stop
+      @server&.shutdown
+    end
+
+    # Rack application for use with Puma, etc.
+    def self.rack_app(schema_dir:, **config)
+      server = new(schema_dir: schema_dir, **config)
+      
+      lambda do |env|
+        server.handle_rack_request(env)
+      end
+    end
+
+    # Handle Rack request
+    def handle_rack_request(env)
+      request = RackRequest.new(env)
+      response = RackResponse.new
+      
+      handle_request_internal(request, response)
+      
+      [response.status, response.headers, [response.body]]
+    end
+
+    class << self
+      def start(**options)
+        new(**options).start
+      end
+    end
+
+    private
+
+    def print_banner
+      puts <<~BANNER
+        
+        ╔══════════════════════════════════════════════════════════════════╗
+        ║                                                                  ║
+        ║   🚀 Synthra API Server v#{VERSION}                            ║
+        ║                                                                  ║
+        ║   Production-Ready Data Generation API                           ║
+        ║                                                                  ║
+        ╠══════════════════════════════════════════════════════════════════╣
+        ║                                                                  ║
+        ║   Server:      http://#{@config[:host]}:#{@config[:port]}#{" " * (29 - @config[:host].length - @config[:port].to_s.length)}║
+        ║   Environment: #{@config[:environment].to_s.ljust(42)}║
+        ║   Schemas:     #{@registry.names.count.to_s.ljust(42)}║
+        ║                                                                  ║
+        ╚══════════════════════════════════════════════════════════════════╝
+        
+        📊 Available Schemas:
+        #{@registry.names.map { |n| "   • #{n}" }.join("\n")}
+        
+        🔗 API Endpoints:
+           GET  /                          Health check
+           GET  /api/schemas               List schemas
+           GET  /api/:schema               Generate record
+           GET  /api/:schema/batch         Generate batch
+           GET  /api/:schema/stream        Stream records (NDJSON)
+           POST /api/:schema               Generate with overrides
+           GET  /api/:schema/openapi       OpenAPI spec for schema
+           GET  /api/:schema/protobuf      Protobuf spec for schema
+           GET  /metrics                   Server metrics
+        
+        Press Ctrl+C to stop
+        
+      BANNER
+    end
+
+    def setup_signal_handlers
+      trap("INT") { stop }
+      trap("TERM") { stop }
+    end
+
+    def create_logger
+      WEBrick::Log.new(
+        $stderr,
+        @config[:log_level] == :debug ? WEBrick::Log::DEBUG : WEBrick::Log::INFO
+      )
+    end
+
+    def handle_request(req, res)
+      # :nocov: WEBrick mount_proc glue — wraps live WEBrick request/response objects.
+      request = WEBrickRequest.new(req)
+      response = WEBrickResponse.new(res)
+      handle_request_internal(request, response)
+      # :nocov:
+    end
+
+    def handle_request_internal(request, response)
+      start_time = Time.now
+      
+      # CORS
+      add_cors_headers(response) if @config[:cors]
+      
+      if request.options?
+        response.status = 204
+        return
+      end
+      
+      # Authentication
+      if @config[:auth] && !authenticate(request)
+        response.status = 401
+        response.json({ error: "Unauthorized" })
+        return
+      end
+      
+      # Rate limiting
+      if @rate_limiter && @rate_limiter.limited?(request.client_ip)
+        response.status = 429
+        response.json({ error: "Rate limit exceeded", retry_after: @rate_limiter.retry_after(request.client_ip) })
+        return
+      end
+      
+      # Route
+      route(request, response)
+      
+      # Metrics
+      if @metrics
+        @metrics.record(
+          path: request.path,
+          method: request.method,
+          status: response.status,
+          duration: Time.now - start_time
+        )
+      end
+    rescue StandardError => e
+      handle_error(e, response)
+    end
+
+    def route(request, response)
+      case request.path
+      when "/"
+        handle_health(response)
+      when "/api/schemas"
+        handle_list_schemas(response)
+      when "/metrics"
+        handle_metrics(response)
+      when %r{^/api/([^/]+)/openapi$}
+        handle_openapi(request, response, $1)
+      when %r{^/api/([^/]+)/protobuf$}
+        handle_protobuf(request, response, $1)
+      when %r{^/api/([^/]+)/batch$}
+        handle_batch(request, response, $1)
+      when %r{^/api/([^/]+)/stream$}
+        handle_stream(request, response, $1)
+      when %r{^/api/([^/]+)$}
+        if request.post?
+          handle_generate_post(request, response, $1)
+        else
+          handle_generate(request, response, $1)
+        end
+      else
+        response.status = 404
+        response.json({ error: "Not found", path: request.path })
+      end
+    end
+
+    def handle_health(response)
+      response.json({
+        status: "healthy",
+        version: VERSION,
+        schemas: @registry.names.count,
+        uptime: uptime
+      })
+    end
+
+    def handle_list_schemas(response)
+      response.json({
+        schemas: @registry.names.sort.map do |name|
+          schema = @registry.schema(name)
+          {
+            name: name,
+            fields: schema.fields.count,
+            endpoint: "/api/#{to_snake_case(name)}"
+          }
+        end
+      })
+    end
+
+    def handle_generate(request, response, schema_slug)
+      schema = find_schema(schema_slug)
+      return schema_not_found(response, schema_slug) unless schema
+      
+      params = request.query_params
+      cache_key = "#{schema.name}:#{params[:seed]}:#{params[:mode]}"
+      
+      if @cache && (cached = @cache.get(cache_key))
+        response.json(cached)
+        return
+      end
+      
+      data = schema.generate(
+        seed: params[:seed]&.to_i,
+        mode: (params[:mode] || @config[:default_mode] || :random).to_sym,
+        registry: @registry
+      )
+      
+      @cache&.set(cache_key, data)
+      response.json(data)
+    end
+
+    def handle_generate_post(request, response, schema_slug)
+      schema = find_schema(schema_slug)
+      return schema_not_found(response, schema_slug) unless schema
+      
+      body = request.json_body || {}
+      count = [body["count"] || 1, @config[:max_batch_size]].min
+      
+      if count > 1
+        data = schema.generate_many(
+          count,
+          seed: body["seed"]&.to_i,
+          mode: (body["mode"] || :random).to_sym,
+          overrides: body["overrides"] || {},
+          registry: @registry
+        )
+      else
+        data = schema.generate(
+          seed: body["seed"]&.to_i,
+          mode: (body["mode"] || :random).to_sym,
+          overrides: body["overrides"] || {},
+          registry: @registry
+        )
+      end
+      
+      response.json(data)
+    end
+
+    def handle_batch(request, response, schema_slug)
+      schema = find_schema(schema_slug)
+      return schema_not_found(response, schema_slug) unless schema
+      
+      params = request.query_params
+      count = [[params[:count]&.to_i || 10, 1].max, @config[:max_batch_size]].min
+      
+      data = schema.generate_many(
+        count,
+        seed: params[:seed]&.to_i,
+        mode: (params[:mode] || :random).to_sym,
+        registry: @registry
+      )
+      
+      response.json({
+        data: data,
+        meta: {
+          count: data.length,
+          schema: schema.name,
+          seed: params[:seed]&.to_i,
+          mode: params[:mode] || "random"
+        }
+      })
+    end
+
+    def handle_stream(request, response, schema_slug)
+      schema = find_schema(schema_slug)
+      return schema_not_found(response, schema_slug) unless schema
+      
+      params = request.query_params
+      count = [[params[:count]&.to_i || 100, 1].max, @config[:max_stream_size]].min
+      
+      response.content_type = "application/x-ndjson"
+      
+      output = +""
+      schema.generate_stream(count: count, mode: (params[:mode] || :random).to_sym).each do |record|
+        output << JSON.generate(record) << "\n"
+      end
+      response.body = output
+    end
+
+    def handle_openapi(request, response, schema_slug)
+      schema = find_schema(schema_slug)
+      return schema_not_found(response, schema_slug) unless schema
+      
+      # Create a mini registry with just this schema
+      mini_registry = Registry.new
+      mini_registry.register_schema(schema.name, schema)
+      
+      exporter = Export::OpenAPI.new(mini_registry)
+      spec = exporter.export_as(request.query_params[:format]&.to_sym || :yaml)
+      
+      response.content_type = request.query_params[:format] == "json" ? "application/json" : "application/yaml"
+      response.body = spec
+    end
+
+    def handle_protobuf(request, response, schema_slug)
+      schema = find_schema(schema_slug)
+      return schema_not_found(response, schema_slug) unless schema
+      
+      exporter = Export::Protobuf.new(schema, registry: @registry)
+      proto = exporter.export
+      
+      response.content_type = "text/plain"
+      response.body = proto
+    end
+
+    def handle_metrics(response)
+      if @metrics
+        response.json(@metrics.to_h)
+      else
+        response.json({ enabled: false })
+      end
+    end
+
+    def find_schema(slug)
+      # Try exact match first
+      return @registry.schema(slug) if @registry.schema?(slug)
+      
+      # Try PascalCase
+      pascal = slug.split("_").map(&:capitalize).join
+      return @registry.schema(pascal) if @registry.schema?(pascal)
+      
+      # Try case-insensitive match
+      @registry.names.find { |n| n.downcase == slug.downcase }&.then { |n| @registry.schema(n) }
+    end
+
+    def schema_not_found(response, slug)
+      response.status = 404
+      response.json({
+        error: "Schema not found",
+        requested: slug,
+        available: @registry.names.map { |n| to_snake_case(n) }
+      })
+    end
+
+    def authenticate(request)
+      return true unless @config[:auth]
+
+      case @config[:auth][:type]
+      when :api_key
+        # SECURITY: header only (never the query string — keys in URLs leak into access logs,
+        # browser history and Referer headers) and a constant-time compare (Array#include? leaks
+        # the key length/prefix via a timing oracle).
+        secure_match?(request.headers["X-API-Key"], @config[:auth][:keys])
+      when :bearer
+        auth = request.headers["Authorization"]
+        return false unless auth&.start_with?("Bearer ")
+
+        secure_match?(auth[7..], @config[:auth][:tokens])
+      else
+        true
+      end
+    end
+
+    # Constant-time membership test against a list of secrets. fixed_length_secure_compare raises on
+    # length mismatch, so the bytesize guard short-circuits non-matches without leaking timing.
+    def secure_match?(provided, allowed)
+      return false unless provided.is_a?(String) && allowed
+
+      allowed.any? do |candidate|
+        candidate.is_a?(String) &&
+          candidate.bytesize == provided.bytesize &&
+          OpenSSL.fixed_length_secure_compare(candidate, provided)
+      end
+    end
+
+    def add_cors_headers(response)
+      response.headers["Access-Control-Allow-Origin"] = "*"
+      response.headers["Access-Control-Allow-Methods"] = "GET, POST, OPTIONS"
+      response.headers["Access-Control-Allow-Headers"] = "Content-Type, Authorization, X-API-Key"
+      response.headers["Access-Control-Max-Age"] = "86400"
+    end
+
+    def handle_error(error, response)
+      response.status = 500
+      response.json({
+        error: error.class.name,
+        message: error.message,
+        backtrace: @config[:environment] == :development ? error.backtrace&.first(10) : nil
+      })
+    end
+
+    def uptime
+      @start_time ||= Time.now
+      (Time.now - @start_time).round
+    end
+
+    def to_snake_case(str)
+      str.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+         .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+         .downcase
+    end
+
+    # Simple metrics collector
+    class Metrics
+      def initialize
+        @requests = Hash.new(0)
+        @durations = Hash.new { |h, k| h[k] = [] }
+        @errors = Hash.new(0)
+        @mutex = Mutex.new
+      end
+
+      def record(path:, method:, status:, duration:)
+        @mutex.synchronize do
+          key = "#{method} #{path}"
+          @requests[key] += 1
+          @durations[key] << duration
+          @errors[key] += 1 if status >= 400
+        end
+      end
+
+      def to_h
+        @mutex.synchronize do
+          {
+            total_requests: @requests.values.sum,
+            endpoints: @requests.map do |key, count|
+              durations = @durations[key]
+              {
+                endpoint: key,
+                requests: count,
+                errors: @errors[key],
+                avg_duration_ms: (durations.sum / durations.length * 1000).round(2),
+                p99_duration_ms: (percentile(durations, 99) * 1000).round(2)
+              }
+            end
+          }
+        end
+      end
+
+      private
+
+      def percentile(array, p)
+        return 0 if array.empty?
+        sorted = array.sort
+        k = (p / 100.0 * (sorted.length - 1)).floor
+        sorted[k]
+      end
+    end
+
+    # Simple rate limiter
+    class RateLimiter
+      def initialize(limit_per_minute)
+        @limit = limit_per_minute
+        @counts = Hash.new { |h, k| h[k] = { count: 0, reset_at: Time.now + 60 } }
+        @mutex = Mutex.new
+      end
+
+      def limited?(ip)
+        @mutex.synchronize do
+          entry = @counts[ip]
+          
+          if Time.now > entry[:reset_at]
+            entry[:count] = 0
+            entry[:reset_at] = Time.now + 60
+          end
+          
+          entry[:count] += 1
+          entry[:count] > @limit
+        end
+      end
+
+      def retry_after(ip)
+        # Same mutex as #limited? — @counts has a default block, so even a read can mutate the hash.
+        @mutex.synchronize do
+          entry = @counts[ip]
+          [entry[:reset_at] - Time.now, 0].max.ceil
+        end
+      end
+    end
+
+    # Simple cache
+    class Cache
+      def initialize(ttl)
+        @ttl = ttl
+        @store = {}
+        @mutex = Mutex.new
+      end
+
+      def get(key)
+        @mutex.synchronize do
+          entry = @store[key]
+          return nil unless entry
+          return nil if Time.now > entry[:expires_at]
+          entry[:value]
+        end
+      end
+
+      def set(key, value)
+        @mutex.synchronize do
+          @store[key] = { value: value, expires_at: Time.now + @ttl }
+        end
+      end
+    end
+
+    # Request adapter for WEBrick
+    class WEBrickRequest
+      def initialize(req)
+        @req = req
+      end
+
+      def path
+        @req.path
+      end
+
+      def method
+        @req.request_method
+      end
+
+      def options?
+        method == "OPTIONS"
+      end
+
+      def post?
+        method == "POST"
+      end
+
+      def query_params
+        @req.query || {}
+      end
+
+      def headers
+        Hash[@req.header.map { |k, v| [k.tr("_", "-").downcase, v.first] }]
+      end
+
+      def client_ip
+        @req.peeraddr[2]
+      end
+
+      def json_body
+        JSON.parse(@req.body || "{}") rescue {}
+      end
+    end
+
+    # Response adapter for WEBrick
+    class WEBrickResponse
+      attr_accessor :status
+      attr_reader :headers
+
+      def initialize(res)
+        @res = res
+        @headers = {}
+      end
+
+      def status=(code)
+        @res.status = code
+      end
+
+      def status
+        @res.status
+      end
+
+      def content_type=(type)
+        @res["Content-Type"] = type
+      end
+
+      def body=(content)
+        @res.body = content
+      end
+
+      def json(data)
+        @res["Content-Type"] = "application/json"
+        @res.body = JSON.pretty_generate(data)
+      end
+
+      def headers
+        @res.header
+      end
+    end
+
+    # Request adapter for Rack
+    class RackRequest
+      def initialize(env)
+        @env = env
+        @request = Rack::Request.new(env) if defined?(Rack::Request)
+      end
+
+      def path
+        @env["PATH_INFO"]
+      end
+
+      def method
+        @env["REQUEST_METHOD"]
+      end
+
+      def options?
+        method == "OPTIONS"
+      end
+
+      def post?
+        method == "POST"
+      end
+
+      def query_params
+        return {} unless @request
+        @request.params.transform_keys(&:to_sym)
+      end
+
+      def headers
+        @env.select { |k, _| k.start_with?("HTTP_") }
+            .transform_keys { |k| k[5..].tr("_", "-").downcase }
+      end
+
+      def client_ip
+        @env["REMOTE_ADDR"]
+      end
+
+      def json_body
+        body = @env["rack.input"]&.read
+        @env["rack.input"]&.rewind
+        JSON.parse(body || "{}") rescue {}
+      end
+    end
+
+    # Response adapter for Rack
+    class RackResponse
+      attr_accessor :status, :body
+      attr_reader :headers
+
+      def initialize
+        @status = 200
+        @headers = { "Content-Type" => "application/json" }
+        @body = ""
+      end
+
+      def content_type=(type)
+        @headers["Content-Type"] = type
+      end
+
+      def json(data)
+        @headers["Content-Type"] = "application/json"
+        @body = JSON.pretty_generate(data)
+      end
+    end
+  end
+end